fuul-mcp

@fuul/mcp-server

Fuul Model Context Protocol server for managing affiliate programs, analytics, incentives, and payouts through MCP-compatible clients (Claude Code, Cursor, Claude Desktop).

---

Table of Contents

• Quick Start
• Installation Methods
  • Claude Code Plugin (Recommended)
  • Cursor IDE
  • npx (Any MCP Client)
  • Local Development (Clone)
• Authentication
• Configuration
• MCP Tool Reference
• Troubleshooting
• Repository Layout
• Scripts Reference
• Documentation
• CI and Releases
• License

---

Quick Start

# 1. Install (choose one method below)
# 2. Authenticate once:
npx -y --package=@fuul/mcp-server@latest fuul-mcp login

# 3. Verify:
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

---

Installation Methods

1. Claude Code Plugin (Recommended)

The easiest way to use Fuul MCP with Claude Code. Adds the MCP server plus a skill that documents how to use Fuul tools.

Step 1: Install the plugin

/plugin marketplace add kuyen-labs/mcp_server
/plugin install fuul-mcp@fuul-mcp

Step 2: Verify the .mcp.json format

Check the plugin's .mcp.json at:

~/.claude/plugins/cache/fuul-mcp/fuul-mcp/<version>/.mcp.json

It must use the --package= format in args:

{
  "mcpServers": {
    "fuul": {
      "command": "npx",
      "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
      "env": {
        "FUUL_API_BASE_URL": "${user_config.FUUL_API_BASE_URL}"
      }
    }
  }
}

If args shows ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"] (without --package=), update it to match the format above.

Step 3: Reload the plugin

/reload-plugins

Step 4: Authenticate (one-time)

Open a terminal and run:

npx -y --package=@fuul/mcp-server@latest fuul-mcp login

This opens your browser for OAuth. Tokens are saved to ~/.fuul/tokens.json.

Step 5: Verify

npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Optional: Use staging environment

Set FUUL_API_BASE_URL in the plugin's user settings:

Environment	URL
Production (default)	https://api.fuul.xyz
Staging	https://api.stg.fuul.xyz

---

2. Cursor IDE

Option A: Using npx (no clone required)

1. Authenticate first:

   npx -y --package=@fuul/mcp-server@latest fuul-mcp login
   npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami
   

2. Configure MCP in Cursor:

   Go to Settings → MCP or edit your mcp.json:

   {
     "mcpServers": {
       "fuul": {
         "command": "npx",
         "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
         "env": {
           "FUUL_API_BASE_URL": "https://api.fuul.xyz"
         }
       }
     }
   }
   

Option B: Using local clone

1. Clone and build:

   git clone https://github.com/kuyen-labs/mcp_server.git
   cd mcp_server
   npm ci
   npm run build
   

2. Authenticate:

   npm run cli -- login
   npm run cli -- whoami
   

3. Configure MCP in Cursor:

   {
     "mcpServers": {
       "fuul": {
         "command": "node",
         "args": ["C:\\path\\to\\mcp_server\\dist\\index.js"],
         "cwd": "C:\\path\\to\\mcp_server"
       }
     }
   }
   

   On macOS/Linux:

   {
     "mcpServers": {
       "fuul": {
         "command": "node",
         "args": ["/path/to/mcp_server/dist/index.js"],
         "cwd": "/path/to/mcp_server"
       }
     }
   }
   

---

3. npx (Any MCP Client)

Use the published npm package without cloning:

Command	Purpose
npx -y --package=@fuul/mcp-server@latest fuul-mcp login	Browser OAuth; writes ~/.fuul/tokens.json
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami	Verify session (GET /api/v1/auth/user)
npx -y --package=@fuul/mcp-server@latest fuul-mcp logout	Clear tokens
npx -y --package=@fuul/mcp-server@latest fuul-mcp-server	Start stdio MCP server

For MCP client configs (JSON), use the --package= format:

{
  "command": "npx",
  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
}

---

4. Local Development (Clone)