# flashid-mcp

[中文文档](./README.zh.md)

MCP (Model Context Protocol) server for the [FlashID](https://flashid.app) client. It lets AI agents — Claude Code, Claude Desktop, Cursor and any other MCP client — manage your FlashID browser profiles, tags, proxies and folders, and open/close browsers with automation endpoints, all through natural language.

## Requirements

- The FlashID desktop app installed and running, with **Local API enabled** (FlashID → Settings → Local API)
- Your FlashID **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
```

### Claude Desktop / Cursor

```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 for authenticated connection checks and all business tools) |
| `FLASHID_API_PORT` | `58931` | Port of the FlashID Local API, if you changed it in Settings |

CLI flags `--api-key` / `--port` override the environment.

## 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 3 Windows 11 profiles named shop-1..3, 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 by FlashID. Pass `tag_uuids` to `create_profile` / `update_profile`, or use the attach/detach tools to manage profile tags independently. For a rotating residential proxy, set `proxy.session_sticky_ttl` to `30`, `60`, `90`, or `120`; omit it on create for the default 30 minutes, or on update to preserve the current duration.

### Page automation

`open_browser` returns CDP automation endpoints:

```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.

## Troubleshooting

Run the `check_connection` tool first — it verifies that the FlashID app is reachable and that the configured API key is valid. Full API reference: [www.flashid.net/api-reference](https://www.flashid.net/api-reference).

## Development

```bash
npm install
npm run build        # tsc → dist/
npm test             # vitest
npm run check-coverage  # tool coverage vs contract/openapi.json
```

## License

[MIT](./LICENSE)