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.

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

31 tools by default, each mapping to one FitNesse responder. Set FITNESSE_COMPLETE_TOOLSET=1 to expose 11 additional lower-traffic tools (42 total), and FITNESSE_ALLOW_SHUTDOWN=1 to also expose fitnesse_shutdown (43 with both). Under FITNESSE_READONLY, only the read tools are exposed — 13 by default, or 23 with FITNESSE_COMPLETE_TOOLSET=1.

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://localhost:8000/mcp" }
  }
}

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

Interactive testing

Create fastmcp.json file.

./scripts/run-inspector.sh

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

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

• test — installs dev dependencies; used by scripts/release.sh to run the test suite without requiring Python on the host

• production — used by Docker Compose for deployment

Release

Releasing is split into two scripts so cutting a release doesn't require Docker registry access, and publishing the image doesn't require pushing to git. scripts/release-and-publish.sh runs both in sequence.

scripts/release.sh — tests, version bump, git tag

Prerequisites: clean working tree, checked out on main; push access to origin; docker (to run the test suite — no local Python needed); gh auth login, if you want the GitHub release created automatically.

bash scripts/release.sh 0.2.0

This runs, in order:

1. Builds the test Docker target and runs pytest inside it — aborts the release on failure

2. Bumps version in pyproject.toml to 0.2.0

3. Commits the bump and tags it v0.2.0

4. Pushes the commit and the v0.2.0 tag to origin

5. Opens a GitHub release for v0.2.0 via gh (prints the manual-create link instead if gh isn't installed)

scripts/docker-build-and-publish.sh — build + push the image

Prerequisites: docker login harbor.netcare.local (or export FITNESSE_MCP_REGISTRY to target a different registry).

bash scripts/docker-build-and-publish.sh 0.2.0

Builds the production Docker target tagged 0.2.0 and latest, then pushes both to harbor.netcare.local/fitnesse-mcp. Run it from the tagged commit (e.g. right after release.sh, or after git checkout v0.2.0 later); if the version is omitted it's read from pyproject.toml.

scripts/release-and-publish.sh — both, in one step

bash scripts/release-and-publish.sh 0.2.0

Production with Docker Compose

docker compose up --build -d

Env vars come from a .env file alongside docker-compose.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_COMPLETE_TOOLSET=1
# FITNESSE_UPLOAD_ROOT=/data/uploads

The server is then available at http://localhost:8000/mcp or through the stdio-to-html-proxy for stdio-only clients:

{
  "mcpServers": {
    "fitnesse": {
      "command": "docker",
      "args": [
        "exec", "-i", "fitnesse-mcp",
        "fastmcp", "run", "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}