flarum-mcp

An MCP server for Flarum forums. It lets any MCP client (Claude Code, Claude Desktop, …) search, read, and post discussions through Flarum's REST/JSON:API. Read tools need no auth; write tools use a personal access token. Ships preconfigured for reverser.id.

Tools

Tool	Auth	What it does
list_tags	–	List categories/labels with id, slug, description, count
search_discussions	–	Full-text search discussions
recent_discussions	–	Most recently active discussions
discussions_by_tag	–	Discussions under a tag slug (e.g. malware-analysis)
get_discussion	–	Read a discussion + its posts as plain text
create_discussion	token	Start a new discussion (needs ≥1 tag id); optional attachments
reply_to_discussion	token	Reply to an existing discussion; optional attachments
upload_file	token	Upload an image/file (local path or URL) → embed snippet

create_discussion and reply_to_discussion accept an optional attachments array of local file paths or http(s) URLs — each is uploaded and embedded in the post (images render inline, other files as download links). Uploading requires the fof/upload extension enabled on the forum.

Configuration

Env var	Required	Default
FLARUM_BASE_URL	no	https://reverser.id
FLARUM_USERNAME (or FLARUM_EMAIL)	write tools	–
FLARUM_PASSWORD	write tools	–
FLARUM_API_TOKEN	optional alternative to the above	–

Auth is only needed for the write tools (create_discussion, reply_to_discussion); read tools work anonymously.

The recommended way is to just give it a username/email + password — the server logs in for you via POST /api/token and caches the token for the life of the process, so you never mint one by hand:

"env": {
  "FLARUM_BASE_URL": "https://reverser.id",
  "FLARUM_USERNAME": "your-username",
  "FLARUM_PASSWORD": "your-password"
}

Prefer not to store a password? Supply a ready-made token instead (takes precedence if set):

curl -s https://reverser.id/api/token -H 'Content-Type: application/json' \
  -d '{"identification":"USERNAME_OR_EMAIL","password":"PASSWORD"}'
# -> {"token":"xxxxxxxxxxxx...","userId":1}
# then set FLARUM_API_TOKEN to that value

Legacy REVERSER_* names (REVERSER_BASE_URL, REVERSER_USERNAME, REVERSER_PASSWORD, REVERSER_API_TOKEN) are still read as fallbacks.

Use with Claude Code

Once published, no install needed — run it with npx:

claude mcp add flarum-mcp \
  --env FLARUM_BASE_URL=https://reverser.id \
  --env FLARUM_USERNAME=your-username \
  --env FLARUM_PASSWORD=your-password \
  -- npx -y flarum-mcp

Or a project-local .mcp.json:

{
  "mcpServers": {
    "flarum-mcp": {
      "command": "npx",
      "args": ["-y", "flarum-mcp"],
      "env": {
        "FLARUM_BASE_URL": "https://reverser.id",
        "FLARUM_USERNAME": "your-username",
        "FLARUM_PASSWORD": "your-password"
      }
    }
  }
}

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flarum-mcp": {
      "command": "npx",
      "args": ["-y", "flarum-mcp"],
      "env": {
        "FLARUM_BASE_URL": "https://reverser.id",
        "FLARUM_USERNAME": "your-username",
        "FLARUM_PASSWORD": "your-password"
      }
    }
  }
}

Local development

git clone https://github.com/ReverserID/flarum-mcp.git
cd flarum-mcp
npm install          # runs the build via the "prepare" script
npm start            # node build/index.js

Quick manual test — handshake + list_tags over stdio, no client needed:

printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_tags","arguments":{}}}' \
 | node build/index.js

Layout

flarum-mcp/
├── src/
│   ├── index.ts     # MCP server + tool definitions
│   └── flarum.ts     # tiny Flarum JSON:API client + helpers
├── package.json
├── tsconfig.json
├── .env.example
└── LICENSE

Notes

• stdio transport uses stdout for the protocol — the server only ever logs to stderr. Keep it that way if you extend it.
• Extend with more tools (likes, flags, user lookup, notifications) by following the same server.registerTool(...) pattern.

License

MIT © ReverserID