FogBugz MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to a live FogBugz instance. Search and manage cases, track history, assign and resolve — all from a natural language conversation. Works with on-premise and on-demand FogBugz installations.

Features

• Search and list cases using FogBugz query syntax (e.g. `project:Website status:Active`)
• Read case details including full event and comment history
• Create and update cases — set title, project, area, milestone, priority, and comments
• Full lifecycle management — assign, resolve, reopen, and close cases
• User, project, and area discovery — list people, categories, projects, milestones, and statuses
• Create new projects directly from the conversation
• Automatic API selection — detects your FogBugz version and switches between XML and JSON API automatically

Requirements

• FogBugz (on-premise or on-demand)
• Node.js 20 or later
• A FogBugz API token

Getting a FogBugz API Token

You need an API token to authenticate the MCP server with FogBugz. There are two ways to obtain one:

Via the web UI

Go to Account & Settings → User Options and click the Create API Token link.

See the official guide: Create API Token using the FogBugz UI

Via API request

Send the following request (replace placeholders with your values):

https://[your-fogbugz-server]/api.asp?cmd=logon&email=[your-email]&password=[your-password]

The response will contain your API token.

See the official guide: Get an API Token using FogBugz API commands

AI Client Setup

MCP is an open standard — this server works with any MCP-compatible AI client. Configuration varies by client.

Claude Desktop ✓ (tested)

One-click install: Download the latest `.mcpb` package from the Releases page and open it — Claude Desktop will install and configure the server automatically, prompting you for your FogBugz URL and API token.

Manual configuration: Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

{
  "mcpServers": {
    "fogbugz": {
      "command": "npx",
      "args": ["-y", "@todevs/fogbugz-mcp"],
      "env": {
        "FOGBUGZ_URL": "https://your-fogbugz-server.com",
        "FOGBUGZ_API_KEY": "your-api-token"
      }
    }
  }
}

Claude Code ✓ (tested)

Add to `.mcp.json` in your project root:

{
  "mcpServers": {
    "fogbugz": {
      "command": "npx",
      "args": ["-y", "@todevs/fogbugz-mcp"],
      "env": {
        "FOGBUGZ_URL": "https://your-fogbugz-server.com",
        "FOGBUGZ_API_KEY": "your-api-token"
      }
    }
  }
}

Other MCP-compatible clients

Any client that supports MCP stdio servers should work. Consult your client's documentation for how to register a stdio MCP server with environment variables. The server entry point is `npx @todevs/fogbugz-mcp` (or `node /path/to/dist/index.js` for a local build).

Tools

Case Management

Search & View

Reference Data

Advanced

Usage Examples

Example 1: Finding open bugs in a project

You: "Show me all open bugs in the Website project assigned to nobody."

Claude calls: `search_cases` with query `project:Website status:Active assignedTo:nobody category:Bug`.

Result: A list of unassigned bugs with their IDs, titles, and creation dates — ready to triage or assign.

Example 2: Creating a case from a bug report

You: "Create a bug in the Mobile project titled 'Login button unresponsive on iOS 17', assign it to alice, and set priority to 2."

Claude calls: `create_case` with project, title, assignee, and priority set in a single call, then `get_case_link` to return a direct URL.

Result: New case created. Claude confirms the case number and provides a link.

Example 3: Resolving a case with a closing comment

You: "Resolve case 1042 and add a comment saying the fix was deployed in v3.5.1."

Claude calls: `resolve_case` with the case ID and a comment describing the fix.

Result: Case resolved. Claude confirms the status change and the comment was saved.

Example 4: Reviewing your team's workload

You: "What open cases does bob have right now?"

Claude calls: `list_people` to find Bob's user ID, then `list_my_cases` filtered to that user.

Result: A summary of Bob's active cases grouped by project, with priorities and due dates.

Example 5: Updating a case after a code review

You: "Move case 987 to the Backend project, change the milestone to v4.0, and leave a comment saying it was re-scoped after the architecture review."

Claude calls: `update_case` with the new project, milestone, and comment all set in one call.

Result: Case updated. Claude confirms each field change.

How It Works

This server implements the Model Context Protocol over stdio. The AI client translates natural language requests into FogBugz queries or API calls, invokes the appropriate tool, and presents the results. The server is a thin proxy — it passes requests directly to your FogBugz instance and returns the response.

API Auto-Detection

At startup the server automatically selects the right API client for your FogBugz instance:

1. Probes `/api.xml` to read the FogBugz version number.

2. If version ≥ 9, attempts to reach the JSON API (`/f/api/0/jsonapi`) — uses `FogBugzJsonClient` on success.

3. Falls back to `FogBugzXmlClient` (XML API via `/api.asp`) for version Note on text formatting: Plain text only is supported in descriptions and comments when connected to FogBugz 8.x via the XML API. HTML and Markdown are stored and displayed literally.

Configuration Reference

Installation

Via npx (no install needed)

# Latest stable release
npx @todevs/fogbugz-mcp

# Latest dev build (pre-release)
npx @todevs/fogbugz-mcp@dev

From source

git clone https://github.com/todevelopers/fogbugz-mcp.git
cd fogbugz-mcp
npm install
npm run build
node dist/index.js https://your-fogbugz-server.com your-api-token

Development

npm run dev    # run via ts-node (no build needed)
npm run build  # compile TypeScript to dist/
npm test       # run all Jest tests

Compatibility

• FogBugz on-premise and on-demand (tested with FogBugz 8.8.53 via XML API)
• Node.js 20+

Privacy Policy

This server does not collect, store, or transmit any data to ToDevelopers or any third party. All communication is directly between your AI client and your own FogBugz instance using the URL and credentials you provide. No usage data, case content, or credentials are sent anywhere other than your configured FogBugz server.

For complete privacy information, see the FogBugz Privacy Policy.

Acknowledgements

This project is based on the original work by Sarasvati Akari Lara-Almeida — thank you for the foundation.

License

MIT © Tomáš Gažovič, ToDevelopers s.r.o.