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