MCP for Flarum

A Model Context Protocol server for Flarum.

It gives any MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, and others) full access to a Flarum forum's API: read and search discussions and posts, create threads and replies, manage users, tags and groups, moderate content, change settings, and call any third-party extension endpoint.

Flarum's whole API is uniform JSON:API, so a small set of generic tools covers the entire surface, including extensions, rather than hundreds of hand-written ones.

Tools

Generic (full API coverage):

Convenience:

Related MCP server: CustomGPT MCP Server

Configuration

Getting an API key

Flarum has no admin UI for API keys yet. Create one directly in the database:

INSERT INTO api_keys (`key`, user_id, created_at)
VALUES (REPLACE(UUID(), '-', ''), 1, NOW());

Use the resulting key as FLARUM_API_KEY. Setting user_id (or FLARUM_USER_ID) makes the key act as that user, so its permissions are exactly that user's permissions.

Install & run

Self-host it with the official Docker image, or build it from source. (It is intentionally not published to npm.)

Option 1: Docker (recommended)

For a local Claude client (stdio):

docker run -i --rm \
  -e FLARUM_URL=https://discuss.example.com \
  -e FLARUM_API_KEY=xxxxx \
  ghcr.io/linkrobins/mcp-for-flarum

Claude Code:

claude mcp add flarum -- docker run -i --rm -e FLARUM_URL=https://discuss.example.com -e FLARUM_API_KEY=xxxxx ghcr.io/linkrobins/mcp-for-flarum

Claude Desktop / Cursor / Windsurf (JSON config):

{
  "mcpServers": {
    "flarum": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FLARUM_URL", "-e", "FLARUM_API_KEY", "ghcr.io/linkrobins/mcp-for-flarum"],
      "env": {
        "FLARUM_URL": "https://discuss.example.com",
        "FLARUM_API_KEY": "xxxxx"
      }
    }
  }
}

Option 2: From source (no Docker)

git clone https://github.com/linkrobins/mcp-for-flarum.git
cd mcp-for-flarum
npm install && npm run build
FLARUM_URL=https://discuss.example.com FLARUM_API_KEY=xxxxx node dist/index.js

Then point your client's command at node /absolute/path/to/mcp-for-flarum/dist/index.js.

Prefer not to run anything?

A managed, hosted version is offered by Link Robins, no install, no key management, and usable from web clients. See linkrobins.com.

Hosting (HTTP transport)

The same binary can run as a long-lived web service over Streamable HTTP, so you can host it instead of running it locally. This is what web-based clients (which can't spawn a local process) connect to.

Start in HTTP mode with --http (or MCP_TRANSPORT=http):

FLARUM_URL=https://discuss.example.com \
FLARUM_API_KEY=xxxxx \
MCP_AUTH_TOKEN=a-long-random-secret \
PORT=3000 \
node dist/index.js --http

It serves:

• POST /mcp — the MCP endpoint (Streamable HTTP, stateless)

• GET /health — health check for load balancers / uptime monitors

Hosting-specific configuration:

Security: a hosted instance can read, write, and delete on the forum its key targets. Always run it behind TLS, set MCP_AUTH_TOKEN (or front it with your own auth/OAuth proxy), and give the API key's user the least privilege it needs. The Flarum API key stays server-side and is never exposed to clients.

Docker (hosted mode)

docker run -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e FLARUM_URL=https://discuss.example.com \
  -e FLARUM_API_KEY=xxxxx \
  -e MCP_AUTH_TOKEN=a-long-random-secret \
  ghcr.io/linkrobins/mcp-for-flarum

HOST=0.0.0.0 is needed so the published port is reachable; the server only allows it because MCP_AUTH_TOKEN is set.

Or use the included docker-compose.yml: set your values and docker compose up -d.

Development

npm install
npm run build
FLARUM_URL=... FLARUM_API_KEY=... node dist/index.js

License

Source-available and proprietary. Copyright (c) 2026 Link Robins. You may self-host and run it for your own use; you may not redistribute it or provide it to others as a hosted service. Link Robins is the only entity permitted to offer it as a hosted service. See LICENSE for the full terms.

Trademarks

Flarum is a trademark of the Flarum Foundation. This is an independent project that works with Flarum via its API; it is not affiliated with, endorsed by, or sponsored by the Flarum Foundation.