Skip to main content

​
MCP Server Setup

This guide walks through configuring the CodeFire MCP server for each supported AI CLI tool.

​
Prerequisites

  1. CodeFire installed: Download from GitHub Releases and drag to /Applications
  2. Launch CodeFire once: This creates the database and installs the MCP server binary to: 
    ~/Library/Application Support/CodeFire/bin/CodeFireMCP
  3. AI CLI tool installed: Claude Code, Gemini CLI, Codex CLI, or OpenCode
CodeFire includes a one-click installer for the MCP server:
  1. Open CodeFire
  2. Go to Settings (Cmd + ,) → MCP Server tab
  3. Click Install for [Your CLI Tool]
The installer automatically detects which AI tools you have installed and adds the MCP server to their configuration files.

​
Manual Setup

If you prefer to configure manually, follow the instructions for your CLI tool below.

​
Configuration

Run this command to register the CodeFire MCP server:
claude mcp add codefire ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
This adds the server to ~/.claude/mcp.json.

​
Verification

  1. Navigate to a project directory that exists in CodeFire
  2. Start a Claude Code session: 
    cd ~/projects/my-app
claude
  3. In the Claude session, type: 
    Use the get_current_project tool to show which project was detected
You should see output like:
Current project: my-app
Project ID: abc123
Working directory: /Users/you/projects/my-app

​
Troubleshooting

“CodeFire database not found” error
  • Launch the CodeFire GUI app at least once to initialize the database
“No project detected” message
  • Make sure you’ve added the project to CodeFire (it should appear in the sidebar)
  • Verify the current directory matches the project path shown in CodeFire
  • Use list_projects to see all available projects and their paths

​
Configuration

Add the MCP server to Gemini’s settings file:
# Create settings.json if it doesn't exist
mkdir -p ~/.gemini
cat > ~/.gemini/settings.json <<'EOF'
{
  "mcpServers": {
    "codefire": {
      "command": "/Users/YOUR_USERNAME/Library/Application Support/CodeFire/bin/CodeFireMCP",
      "args": []
    }
  }
}
EOF
Important: Replace YOUR_USERNAME with your actual macOS username, or use the full expanded path.

​
Verification

  1. Navigate to a CodeFire project: 
    cd ~/projects/my-app
gemini
  2. Check the connection: 
    List all CodeFire tasks for this project
If the MCP server is connected, Gemini will call the list_tasks tool and show your tasks.

​
Troubleshooting

“MCP server failed to start” error
  • Verify the path to CodeFireMCP is correct and uses the full expanded path (not ~)
  • Check file permissions: ls -l ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
  • The file should be executable. If not, run: 
    chmod +x ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP

​
Configuration

Add the MCP server to Codex’s config file:
# Edit ~/.codex/config.toml
mkdir -p ~/.codex
cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.codefire]
command = "~/Library/Application Support/CodeFire/bin/CodeFireMCP"
args = []
EOF

​
Verification

  1. Start a Codex session in a project directory: 
    cd ~/projects/my-app
codex
  2. Test the connection: 
    Show me the current project from CodeFire
Codex should call get_current_project and display the detected project.

​
Troubleshooting

MCP tools not appearing
  • Check the TOML syntax in ~/.codex/config.toml
  • Ensure there are no duplicate [mcp_servers.codefire] sections
  • Restart Codex after editing the config

​
Configuration

Add the MCP server to OpenCode’s config:
# Edit ~/.opencode/config.json
mkdir -p ~/.opencode
cat > ~/.opencode/config.json <<'EOF'
{
  "mcpServers": {
    "codefire": {
      "command": "~/Library/Application Support/CodeFire/bin/CodeFireMCP",
      "args": []
    }
  }
}
EOF

​
Verification

  1. Navigate to a project and launch OpenCode: 
    cd ~/projects/my-app
opencode
  2. Verify the MCP connection: 
    Use CodeFire to list all my tasks
OpenCode should invoke the list_tasks tool.

​
Troubleshooting

“Command not found” error for CodeFireMCP
  • OpenCode may not expand ~ in the command path
  • Use the full absolute path: 
    "command": "/Users/YOUR_USERNAME/Library/Application Support/CodeFire/bin/CodeFireMCP"

​
Testing the Connection

Once configured, verify the MCP server is working:

​
1. Check Auto-Detection

cd /path/to/your/project
# Start your AI CLI tool and ask:
What is the current CodeFire project?
The agent should call get_current_project and show the detected project name and ID.

​
2. List Projects

Show me all projects in CodeFire
The agent should call list_projects and display all your projects with their IDs and paths.

​
3. Create a Test Task

Create a CodeFire task titled "Test MCP integration" with priority high
The agent should call create_task and confirm the task was created. Open CodeFire to verify the task appears in the task board.

​
4. Check Connection Status in CodeFire

  1. Open CodeFire
  2. Look for the MCP connection indicator (usually in the status bar or toolbar)
  3. It should show:
    • Connected status
    • Current project name
    • Working directory
If you don’t see the indicator, the MCP server may not be running or the connection status file wasn’t created.

​
Connection Lifecycle

​
When MCP Server Starts

  1. Reads the current working directory
  2. Opens the shared SQLite database (~/Library/Application Support/CodeFire/codefire.db)
  3. Queries the database to auto-detect the project
  4. Writes a connection status file to ~/Library/Application Support/CodeFire/mcp-connections/<pid>.json
  5. Begins listening for JSON-RPC messages on stdin

​
During Operation

  • Updates the connection heartbeat on each request
  • CodeFire GUI polls the mcp-connections/ directory to show live connections
  • All database operations use a 5-second busy timeout for safe cross-process access

​
When MCP Server Exits

  • Automatically removes the connection status file
  • Releases the database connection
  • Closes cleanly on SIGTERM or SIGINT

​
Advanced Configuration

​
Custom Database Path

By default, the MCP server looks for the database at: 
~/Library/Application Support/CodeFire/codefire.db
This path is hardcoded and cannot currently be customized. If you’ve moved your CodeFire data, create a symlink: 
ln -s /path/to/custom/location/codefire.db ~/Library/Application\ Support/CodeFire/codefire.db

​
Running Multiple Instances

You can run multiple AI CLI sessions simultaneously. Each spawns its own MCP server process:
  • Each process gets a unique PID
  • Each writes its own connection status file
  • Database locks are managed via WAL mode and busy timeouts
  • CodeFire shows all active connections in the status bar

​
Debugging

The MCP server writes diagnostic messages to stderr. To see them: 
# Run the MCP server manually
~/Library/Application\ Support/CodeFire/bin/CodeFireMCP 2>&1
You’ll see messages like: 
CodeFireMCP: detected project 'my-app' from /Users/you/projects/my-app
If no project is detected: 
CodeFireMCP: no project matched for /Users/you/projects/my-app
This helps diagnose path matching issues.

​
Next Steps

Tools Reference

Browse all available MCP tools

Integration Guide

Learn how to use MCP tools effectively

Build docs developers (and LLMs) love

Get started for freeTalk to us