Flarum Mcp Server

A Model Context Protocol (MCP) server for Flarum forums. This allows Claude Code and other MCP clients to interact with Flarum forums - creating, reading, updating, and deleting discussions, posts, users, and tags.

Installation

Global install (recommended)

npm install -g @btafoya/flarum-mcp-server

npx (no install)

claude mcp add flarum \
  -e FLARUM_BASE_URL=https://your-forum.com \
  -e [email protected] \
  -e FLARUM_PASSWORD=your-password \
  -- npx @btafoya/flarum-mcp-server

Claude Code CLI

Add the server to Claude Code:

claude mcp add flarum \
  -e FLARUM_BASE_URL=https://your-forum.com \
  -e [email protected] \
  -e FLARUM_PASSWORD=your-password \
  -- flarum-mcp-server

If the environment variables are not picked up after running the command above, add the server manually in ~/.claude/settings.json:

{
  "mcpServers": {
    "flarum": {
      "command": "flarum-mcp-server",
      "env": {
        "FLARUM_BASE_URL": "https://your-forum.com",
        "FLARUM_USERNAME": "[email protected]",
        "FLARUM_PASSWORD": "your-password"
      }
    }
  }
}

Remove the server from Claude Code:

claude mcp remove flarum

Environment Variables

Variable	Required	Description
FLARUM_BASE_URL	Yes	Your Flarum forum URL
FLARUM_USERNAME	No	Email or username for auto-login
FLARUM_PASSWORD	No	Password for auto-login

Available Tools

Discussions

Tool	Description
flarum_list_discussions	List discussions (supports filtering by user, tag, date)
flarum_get_discussion	Get discussion details
flarum_create_discussion	Create a new discussion
flarum_update_discussion	Update a discussion
flarum_delete_discussion	Delete/hide a discussion

Posts

Tool	Description
flarum_list_posts	List posts in a discussion
flarum_get_post	Get post details
flarum_create_post	Create a reply
flarum_update_post	Update a post
flarum_delete_post	Delete/hide a post

Users

Tool	Description
flarum_list_users	List users (supports search)
flarum_get_user	Get user details
flarum_create_user	Create a new user
flarum_update_user	Update a user
flarum_delete_user	Delete a user

Tags

Tool	Description
flarum_list_tags	List all tags

Authentication

Tool	Description
flarum_login	Login to the forum
flarum_logout	Logout
flarum_check_auth	Check authentication status

Usage Examples

In Claude Code, you can say:

• "List the latest 10 discussions"
• "Create a new discussion titled 'Hello World' with content 'This is my first post'"
• "Reply to discussion 123 with 'Thanks for sharing!'"
• "Show me all discussions by user john"
• "Get discussions created after 2024-01-01"

Features

• Auto-login: Configure credentials in environment variables for automatic authentication
• Token caching: Tokens are cached locally (~/.flarum-mcp-token.json) with 5-year expiration
• Filtering: Filter discussions by user, tag, and date range
• Soft delete: Default delete operation hides content (recoverable), with option for permanent deletion

Requirements

• Node.js >= 18.0.0
• A Flarum forum with API access

Development

# Clone and install dependencies
git clone https://github.com/btafoya/flarum-mcp-server.git
cd flarum-mcp-server
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT