fitnesse-mcp

An MCP server that exposes FitNesse's REST responders as tools, letting an MCP client read wiki pages, run tests and suites, manage the files section, and inspect test history on a FitNesse instance.

Copyright (c) 2026 netcare GmbH. Released under the MIT License.

Requirements

• VS Code with the Dev Containers extension, plus Docker — the devcontainer supplies the Python toolchain and dependencies

• A reachable FitNesse instance

Working outside the devcontainer? You'll need Python 3.12+ and FastMCP 4, which is currently a prerelease and must be pinned exactly:

pip install "fastmcp==4.0.0b2"

Using uv? fastmcp is a thin wrapper that depends on fastmcp-slim at the same version, and uv only allows prereleases for packages you name explicitly:

[project]
dependencies = ["fastmcp==4.0.0b2"]

[tool.uv]
constraint-dependencies = ["fastmcp-slim==4.0.0b2"]

Pin exactly, not >=4.0.0b1. Each beta in the v4 line has carried breaking changes. This project tracks the prerelease and the pin will move at GA.

Related MCP server: redmine-mcp

Quickstart

1. Open the project in its devcontainer.

git clone https://github.com/netcare-io/fitnesse-mcp.git
cd fitnesse-mcp
code .

VS Code detects .devcontainer/ and prompts to reopen in the container — accept it, or run Dev Containers: Reopen in Container from the command palette (F1). The first build takes a few minutes; later starts are quick. Python and all dependencies are installed inside the container, so there's nothing to set up on your host.

2. Point the server at your FitNesse instance.

Run the remaining commands in the container's terminal:

export FITNESSE_BASE_URL=http://your-fitnesse-host:8080
export FITNESSE_READONLY=1          # recommended for a first run

fastmcp run server.py

localhost in that URL refers to the container, not your host — see Troubleshooting if the connection is refused.

3. Verify it works.

Start the inspector and call fitnesse_get_raw with page_path=FrontPage:

fastmcp-inspector

A successful call returns "ok": true and the raw wiki markup of the page.

Security

This server gives an LLM client the ability to delete pages, purge test history, and roll back versions on your FitNesse instance. Two controls limit that, and both are opt-in:

• Start with FITNESSE_READONLY=1. This hides every write, execute, and control tool, leaving the 23 read-only tools. Open it up deliberately once you know which operations you actually want the model to perform.

• fitnesse_shutdown is not registered at all unless FITNESSE_ALLOW_SHUTDOWN is set. It stops the FitNesse server.

Two further notes:

• Uploads are disabled unless FITNESSE_UPLOAD_ROOT is set, and fitnesse_upload_file will only read files resolving inside that directory.

• Credentials in claude_desktop_config.json are stored in cleartext. For shared machines, prefer the HTTP pattern below with the credentials in the server's own environment.

Environment variables

Tools

42 tools by default (43 with FITNESSE_ALLOW_SHUTDOWN), each mapping to one FitNesse responder. Under FITNESSE_READONLY, only the 23 read tools are exposed.

Pages — read

Pages — write

Tests

History & versions

Search

Files section

Flag-style FitNesse inputs are supported by passing None as a query param value — for example {"nohistory": None} produces ?nohistory.

Connecting an MCP client

Pattern 1 — stdio (simple, local)

The client launches the server as a subprocess and talks over stdin/stdout. No server process to manage.

{
  "mcpServers": {
    "fitnesse": {
      "command": "fastmcp",
      "args": ["run", "server.py"],
      "env": {
        "FITNESSE_BASE_URL": "http://your-fitnesse-host:8080",
        "FITNESSE_USERNAME": "your-username",
        "FITNESSE_PASSWORD": "your-password",
        "FITNESSE_READONLY": "1"
      }
    }
  }
}

Running the server from a Docker image instead? -i keeps stdin open, and each -e forwards one variable from the env block into the container. Every variable you set in env needs its own -e flag — anything missing here is silently ignored inside the container:

{
  "mcpServers": {
    "fitnesse": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "FITNESSE_BASE_URL",
        "-e", "FITNESSE_USERNAME",
        "-e", "FITNESSE_PASSWORD",
        "-e", "FITNESSE_READONLY",
        "fitnesse-mcp:latest"
      ],
      "env": {
        "FITNESSE_BASE_URL": "http://your-fitnesse-host:8080",
        "FITNESSE_USERNAME": "your-username",
        "FITNESSE_PASSWORD": "your-password",
        "FITNESSE_READONLY": "1"
      }
    }
  }
}

Pattern 2 — HTTP (shared, production)

Use this when several clients share one server instance, or when the server runs in Docker. Credentials live in the server's environment rather than in each client's config.

FITNESSE_BASE_URL=http://your-fitnesse-host:8080 \
FITNESSE_USERNAME=your-username \
FITNESSE_PASSWORD=your-password \
fastmcp run server.py --transport http

Listens on port 8000 by default; override with --port.

Most clients can point at the URL directly:

{
  "mcpServers": {
    "fitnesse": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

For clients that only speak stdio, fastmcp run <url> proxies to it.

Interactive testing

fastmcp-inspector

Open the exact URL printed in the terminal — it carries a ?MCP_INSPECTOR_API_TOKEN=... query parameter.

In devcontainers (especially running as root), the wrapper suppresses noisy keyring/DBus warnings:

./scripts/run-inspector.sh

INSPECTOR_RAW_LOGS=1 ./scripts/run-inspector.sh   # unfiltered logs

Troubleshooting

401 Unauthorized — either FITNESSE_USERNAME/FITNESSE_PASSWORD are wrong, or FitNesse isn't configured for authentication and is rejecting the header. Confirm with curl -u user:pass "$FITNESSE_BASE_URL/FrontPage?responder=raw".

Connection refused — check FITNESSE_BASE_URL. Inside a container, localhost is the container, not your host; use host.docker.internal (Docker Desktop) or the host's LAN address.

A write tool is missing — FITNESSE_READONLY is set. Note that any value other than 1/true/yes/on counts as unset.

"truncated": true in a response — the body exceeded FITNESSE_MAX_RESPONSE_BYTES and was cut. Common on suite runs with includehtml. Raise the limit or narrow the request.

Invalid path — the page path contained ?, #, .., or a null byte. FitNesse page paths are dotted (FrontPage.MySuite.MyTest) with no leading slash.

ImportError on startup — almost certainly the FastMCP version. This project targets 4.0.0b2 exactly; v3 and the v4 alphas will not import.

Development

pip install -e ".[dev]"
pytest tests/

The test suite runs the server in-process via fastmcp.Client, so it also verifies the pieces that only fail at call time: dependency injection of timeouts, tag-based tool visibility, and path-injection rejection. Run it after any FastMCP version bump — it doubles as the upgrade tripwire.

Devcontainer

The devcontainer (see Quickstart) builds from a multi-stage Dockerfile at .devcontainer/Dockerfile:

• devcontainer — used by VS Code for development

• production — used by Docker Compose for deployment

Production with Docker Compose

docker compose -f docker-compose.prod.yml up --build -d

Env vars come from a .env file alongside docker-compose.prod.yml:

FITNESSE_BASE_URL=http://your-fitnesse-host:8080
FITNESSE_USERNAME=your-username
FITNESSE_PASSWORD=your-password
FITNESSE_READONLY=1
# FITNESSE_ALLOW_SHUTDOWN=1
# FITNESSE_UPLOAD_ROOT=/data/uploads

The server is then available at http://localhost:8000/mcp.