> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flashid.app/api-reference/mcp/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flashid.app/_mcp/server.

# MCP Server

# FlashID MCP Server

Connect AI agents to FlashID. The `flashid-mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude Code, Codex, Claude Desktop, Cursor and any other MCP client manage your profiles, tags, proxies and folders, and open browsers with automation endpoints — all through natural language, on top of the Local API.

|               |                                                                                |
| ------------- | ------------------------------------------------------------------------------ |
| **Package**   | [`flashid-mcp@0.2.1`](https://www.npmjs.com/package/flashid-mcp/v/0.2.1) (npm) |
| **Transport** | stdio — runs locally next to the FlashID app                                   |
| **Auth**      | Your API key via the `FLASHID_API_KEY` environment variable                    |

## Requirements

* FlashID desktop app installed and running, with **Local API enabled** (FlashID → Settings → Local API)
* Your **API key** (FlashID → Settings → API Access)
* Node.js ≥ 18 (`npx` comes with it)

## Setup

### Claude Code

```bash
claude mcp add flashid -e FLASHID_API_KEY=your-api-key -- npx -y flashid-mcp
```

### Codex

```bash
codex mcp add flashid --env FLASHID_API_KEY=your-api-key -- npx -y flashid-mcp
```

### Claude Desktop / Cursor

Add to your MCP configuration file (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "flashid": {
      "command": "npx",
      "args": ["-y", "flashid-mcp"],
      "env": { "FLASHID_API_KEY": "your-api-key" }
    }
  }
}
```

### Environment variables

| Variable           | Default | Description                                   |
| ------------------ | ------- | --------------------------------------------- |
| `FLASHID_API_KEY`  | —       | Your FlashID API key (required)               |
| `FLASHID_API_PORT` | `58931` | Local API port, if you changed it in Settings |

## Tools

| Group    | Tools                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System   | `check_connection`                                                                                                                                                                             |
| Profiles | `list_profiles` · `get_profile` · `create_profile` · `update_profile` · `quick_update_profile` · `delete_profile` · `star_profile` · `get_fingerprint_options` · `generate_random_fingerprint` |
| Tags     | `list_tags` · `create_tag` · `update_tag` · `delete_tag` · `attach_profile_tag` · `detach_profile_tag`                                                                                         |
| Browsers | `open_browser` · `close_browser` · `list_running_browsers`                                                                                                                                     |
| Proxies  | `list_proxies` · `add_proxies` · `update_proxy` · `delete_proxy` · `check_proxy` · `list_proxy_regions`                                                                                        |
| Folders  | `list_folders` · `create_folder` · `update_folder` · `delete_folder`                                                                                                                           |
| Trash    | `list_trash` · `restore_from_trash` · `permanently_delete`                                                                                                                                     |

## Try it

> Create a tag named ecommerce, create 3 Windows 11 profiles named shop-1..3 with that tag, bind my proxy 1.2.3.4:1080 to them, and open the first one.

`create_profile` only requires `system` — omitted fingerprint fields are auto-generated as a coherent random fingerprint. Pass `tag_uuids` to `create_profile` or `update_profile` to set all profile tags at once, or use `attach_profile_tag` and `detach_profile_tag` to change one association.

## Page automation

`open_browser` returns automation endpoints for the launched browser:

```json
{
  "id": "…",
  "ws": {
    "puppeteer": "ws://127.0.0.1:9222/devtools/browser/…",
    "selenium": "127.0.0.1:9222"
  },
  "debug_port": 9222
}
```

Hand `ws.puppeteer` to Playwright / Puppeteer (`puppeteer.connect({ browserWSEndpoint })`) or to a browser-automation MCP server to drive pages inside the fingerprinted browser.

> **Note**
>
> If any tool fails, run the `check_connection` tool first — it reports whether the FlashID app is reachable and verifies that the API key is valid.