home / mcp / firstpromoter mcp server

FirstPromoter MCP Server

Provides access to FirstPromoter data via an MCP server with tools to list and filter promoters.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "a-petukhov-firstpromoter-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FP_BEARER_TOKEN",
        "-e",
        "FP_ACCOUNT_ID",
        "firstpromoter-mcp"
      ],
      "env": {
        "FP_ACCOUNT_ID": "your_account_id_here",
        "FP_BEARER_TOKEN": "your_token_here"
      }
    }
  }
}

You can connect Claude and other AI assistants to your FirstPromoter data through a dedicated MCP server. This server translates AI requests into FirstPromoter data actions, returning structured results that let you list promoters, filter by criteria, and view metrics, all in a streamlined way.

How to use

You interact with the MCP server by configuring an MCP client to point to the server and then asking natural language questions. Start by running the server locally or via Docker, then connect your AI assistant to the running MCP endpoint. You can request operations such as listing promoters, sorting and filtering by revenue, date joined, or other attributes, and you will receive structured results that your AI can present or summarize.

How to install

Prerequisites you need on your machine before starting are a recent Node.js installation and a FirstPromoter account with API access. You also need an environment to run or test the MCP server with Claude Desktop available.

# 1) Install dependencies
cd firstpromoter-mcp
npm install

# 2) Configure credentials
cp .env.example .env
# Edit .env and add:
# FP_BEARER_TOKEN: your API token from FirstPromoter
# FP_ACCOUNT_ID: your account ID

# 3) Build and run locally
npm run build
npm run dev:stdio
```} ,{

Configuration and running options

The MCP server can run in local stdio mode or be connected via Docker. Use the options shown to integrate with Claude Desktop.

{
  "mcpServers": {
    "firstpromoter": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "FP_BEARER_TOKEN",
        "-e", "FP_ACCOUNT_ID",
        "firstpromoter-mcp"
      ],
      "env": {
        "FP_BEARER_TOKEN": "your_token_here",
        "FP_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}
```} ,{

Security and environment variables

Treat the API token and account ID as secrets. Do not commit the credentials to version control. Use environment variables to supply FP_BEARER_TOKEN and FP_ACCOUNT_ID, and keep their values out of logs.

If you run directly with Node, you can provide the same environment values to your process so the MCP server can authenticate with FirstPromoter.

Troubleshooting

If the server does not appear in Claude Desktop, verify your environment variables are set and the server process is running. Check for build or runtime errors and ensure the Docker image is built when using Docker.

Common issues include invalid credentials, an incorrect Account ID, or rate limiting from FirstPromoter. Ensure FP_BEARER_TOKEN and FP_ACCOUNT_ID are correct and that you are within any applicable usage limits.

Available tools

get_promoters

Lists promoters from your FirstPromoter account with full filtering, sorting, and search capabilities. Supports query, pagination, various filters, and sorting options.