bantamkit — memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop (Python)

bantamkit is a Python MCP server on PyPI that gives coding agents a per-person memory store, JSON Schema validation, shift-work accounting, a token ledger and a skill-catalogue auditor. It works with Claude Code, Claude Desktop, Cursor, GitHub Copilot in VS Code and any stdio MCP client. Install it with pip install "bantamkit[mcp]"; after one install it starts offline.

The same server in pure Node is on npm as bantamkit-mcp. The two share a memory store on disk and a conformance suite holds them to the same answers, so install whichever your host makes easy.

Contents

Install the MCP server

To try it:

pipx run --spec "bantamkit[mcp]" bantamkit-mcp --assets-root

The [mcp] extra pulls the MCP SDK. Without it you still get the library, but the server exits with bantamkit-mcp needs the MCP extra: pip install "bantamkit[mcp]". The uv equivalent, uvx --from "bantamkit[mcp]" bantamkit-mcp, is documented but was not measured here.

A host launches the server every session, so what matters is whether each launch needs the network. For a host, use install once.

Install once, run offline

Recommended.

python -m venv <env>
<env>/bin/pip install "bantamkit[mcp]"
<env>/bin/bantamkit-mcp --install cursor     # or claude, claude-desktop, copilot

--install records the venv's console script by absolute path with "args": [], so no launch needs the network or your shell's PATH. Measured on macOS arm64: that command served 12 tools under a GUI app's PATH, /usr/bin:/bin:/usr/sbin:/sbin. The Windows layout (<env>\Scripts\) was not measured.

No network on the target machine? Carry a wheelhouse. Download on a connected machine with the same OS, CPU architecture and Python minor version (some wheels, such as pydantic_core, are built for one platform only), copy wheels/ across, then install from it:

python -m pip download "bantamkit[mcp]==0.34.0" -d wheels
python -m venv <env>
<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.34.0"
<env>/bin/bantamkit-mcp --install cursor

To move to a newer version, repeat both steps with the new version number. Measurements: docs/install.md → Python package: measured detail.

Run with pipx at every launch

{"mcpServers": {"bantamkit": {"command": "pipx", "args": ["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]}}}

One config line and no venv to keep, but it works offline only while pipx's cache lasts. Measured with the network cut: on a pipx home that had never run it, it exited 1 in 1.33 s; after one online run, it exited 0 in 0.47 s. It needs the package index on a new machine, after the cache is cleared, and whenever pipx decides its cached environment is stale (pipx's policy, not measured). For Claude Code: claude mcp add bantamkit -s user -- pipx run --spec "bantamkit[mcp]" bantamkit-mcp.

Connect it to a host

bantamkit-mcp --install <host> (claude, claude-desktop, copilot, cursor) writes the entry, pointing at the console script you ran. It never prompts, so it behaves the same in a terminal, in CI and inside another agent. For the three JSON hosts it backs the file up first as <name>.backup-<date>, keeps the file's permissions, refuses a file that does not parse, and refuses an entry that differs unless you pass --force.

Each host below has the same steps: 1 command, 2 file, 3 entry, 4 confirm, 5 undo or re-run. The entry's command and args depend on the install route:

To check a recorded command, run it in a terminal: with nothing on stdin it prints usage: bantamkit-mcp ….

Connect to Claude Code

1. Command: <env>/bin/bantamkit-mcp --install claude

2. File: none edited directly. It runs claude mcp add bantamkit -s user -- <command> (user scope, every project), because ~/.claude.json is the host's file and holds state that is not MCP configuration.

3. Entry: printed as ran : claude mcp add bantamkit -s user -- <env>/bin/bantamkit-mcp.

4. Confirm: claude mcp list lists bantamkit. In a session, ask the agent to call bantamkit_status.

5. Undo / re-run: --force does not reach Claude Code, and a second add fails with MCP server bantamkit already exists in user config. Remove first:

   claude mcp remove bantamkit -s user
   <env>/bin/bantamkit-mcp --install claude
   

Connect to Claude Desktop

1. Command: <env>/bin/bantamkit-mcp --install claude-desktop

2. File: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Linux ~/.config/Claude/claude_desktop_config.json

3. Entry (key mcpServers; each entry takes command, args and an optional env):

   {"mcpServers": {"bantamkit": {"command": "/absolute/path/to/env/bin/bantamkit-mcp", "args": []}}}
   

4. Confirm: it prints installed bantamkit into claude-desktop with file, key and command. Fully quit and reopen Claude Desktop, then ask it to call bantamkit_status.

5. Undo / re-run: there is no uninstall flag. Delete the bantamkit entry or restore claude_desktop_config.json.backup-<date>. A matching re-run prints bantamkit is already installed in claude-desktop and matches; a differing entry needs --force.

Connect to Cursor

1. Command: <env>/bin/bantamkit-mcp --install cursor

2. File: ~/.cursor/mcp.json on every OS (%USERPROFILE%\.cursor\mcp.json on Windows); .cursor/mcp.json for one project, by hand.

3. Entry (key mcpServers):

   {"mcpServers": {"bantamkit": {"command": "/absolute/path/to/env/bin/bantamkit-mcp", "args": []}}}
   

4. Confirm: it prints installed bantamkit into cursor and key : mcpServers. Restart Cursor and ask the agent to call bantamkit_status.

5. Undo / re-run: delete the entry or restore mcp.json.backup-<date>. A differing entry, such as an old pipx run one, is refused and printed beside the one it would write; replace it with <env>/bin/bantamkit-mcp --install cursor --force.

Connect to VS Code (GitHub Copilot)

1. Command: <env>/bin/bantamkit-mcp --install copilot

2. File: macOS ~/Library/Application Support/Code/User/mcp.json · Windows %APPDATA%\Code\User\mcp.json · Linux ~/.config/Code/User/mcp.json; .vscode/mcp.json for one workspace, or MCP: Open User Configuration, by hand.

3. Entry: the key is servers, not mcpServers, plus "type": "stdio". This is the detail that catches people out:

   {"servers": {"bantamkit": {"type": "stdio", "command": "/absolute/path/to/env/bin/bantamkit-mcp", "args": []}}}
   

4. Confirm: it prints installed bantamkit into copilot and key : servers. Restart VS Code and ask Copilot to call bantamkit_status.

5. Undo / re-run: delete the entry or restore mcp.json.backup-<date>; --force replaces a differing entry.

Connect other MCP clients

Anything that speaks MCP over stdio runs the same command/args and talks JSON-RPC on stdin and stdout; nothing in this package is host-specific. Codex and a generic JSON config: docs/mcp.md → Client setup.

Configuration

Flags go in the entry's args; environment variables in its env block (or claude mcp add -e NAME=value). Both runtimes print the same --help.

Don't add --store by reflex: the default is layered, and the layering is most of the value. One-shot commands that print and exit: --install {claude,claude-desktop,copilot,cursor} (with --force), --update, --assets-root, --mcp-report, --statusline, -h. More: store binding · pinning · event log · prices.

Update

<env>/bin/bantamkit-mcp --update       # a pip install from PyPI: runs pip install --upgrade bantamkit
pip install -U "bantamkit[mcp]"        # the same, by hand
pipx upgrade bantamkit                 # pipx
uv tool upgrade bantamkit              # uv

--update (check the package index and update this install if it differs, then exit) upgrades an install from PyPI with this interpreter's pip. An editable install, a local file or a source tree is refused with exit 1 and a sentence naming the manual route (for a clone, git pull). It is the only network access here, and only when you type it. For a wheelhouse, repeat the download and install with the new version.

Then restart the server in the host (/mcp → reconnect in Claude Code; a full restart of Claude Desktop): a running server keeps the code it started with. bantamkit_status prints the version and the build_id of the code answering you; a new version with an old build_id means an old process.

Troubleshooting

What it serves

The server serves 12 tools, the bantamkit_status prompt and two resource templates (bantamkit://skills/{name}, bantamkit://rubrics/{name}):

build_identity describes the tree on disk, not the code currently executing — useful precisely when a machine carries two installs under one name. bantamkit_read, the document reader, left the served tools in job50 (2026-09-12); the reader itself stays in the library as bantamkit.docread.

Requirements

Python 3.11 or newer. Three runtime dependencies — httpx, jsonschema, pyyaml — plus mcp under the [mcp] extra.

The asset pack

Contracts, schemas, eval tasks, rubrics and tool manifests ship inside the package and are located at import time:

bantamkit-mcp --assets-root

It prints the resolved directory and its file count. A build that cannot find the pack fails rather than producing an artifact without it — deliberately, because the silent version shipped once. BANTAMKIT_ASSETS overrides the location.

The operator CLI: python -m bantamkit.memory

Memory-store maintenance is separate from the agent-facing tools and is not served over MCP:

python -m bantamkit.memory status     # index size, budget, headroom, archive count
python -m bantamkit.memory lint       # exit 1 if the store is malformed or over budget
python -m bantamkit.memory compact    # archive the stalest facts
python -m bantamkit.memory archived   # list what compaction has moved out
python -m bantamkit.memory archive <name>
python -m bantamkit.memory restore <name>

archive moves a fact out of the store without deleting it; restore brings it back by name. Full reference: docs/memory.md → The operator CLI.

Share a store with the Node server

Both servers read and write the same on-disk format, so either can serve one store. A surface in one and not the other would be a way for two servers to disagree about one person's data, so every feature lands in both in the same change, and a conformance case compares the two answers before it counts as ported.

Where the Python and Node servers differ

• This side's document reader (bantamkit.docread) reads pdf, .doc and .rtf; the Node side refuses them by name. PDF is read by a stdlib reader written for this project; real OLE2 .doc and .rtf go through /usr/bin/textutil, a macOS built-in that is probed at every call and refused by name where it is absent.
• The operator CLI is spelled differently, and it shows in help text and error messages: python -m bantamkit.memory here, bantamkit-memory there. There is no third spelling — a pure-npm install has no Python in it, and CPython does not install that console script.
• build_id hashes the executing tree, and the two runtimes are two trees, so it differs by construction. assets_digest is identical, and that is the one that carries meaning.

Each is recorded in the divergence table with a conformance case pinning the wording, so the difference cannot drift unnoticed.

Development

git clone https://github.com/Ink01101011/bantamkit
cd bantamkit
python -m venv .venv && .venv/bin/pip install -e "runtime-py[dev,mcp]"
.venv/bin/python -m pytest runtime-py/tests -q
.venv/bin/ruff check runtime-py

The cross-runtime gate needs Node:

node tools/conformance/run.mjs --all

Documentation

MIT.