custom_mcp_server

A minimal MCP (Model Context Protocol) server built with the mcp Python SDK. Exposes three tools: add, save_note, search_notes. Built as a learning project — not intended for production use.

Requirements

• Python ≥ 3.10 (mcp[cli] doesn't support 3.9)

• Node.js + npx (only for the MCP Inspector)

Related MCP server: Notes MCP Server

Setup

python3.11 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

Running directly

.venv/bin/python3 server.py

Starts the server on stdio. Meant to be launched by an MCP client (Inspector, Claude Desktop, Claude Code) — not run interactively.

Running with the MCP Inspector

npx @modelcontextprotocol/inspector "$(pwd)/.venv/bin/python3" "$(pwd)/server.py"

Prints a URL with an auth token — open it in your browser. The server card connects automatically over stdio. Ctrl+C to stop.

Testing

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest -q

Runs on every push/PR via GitHub Actions.

Registering with Claude Code

From the project root:

claude mcp add --scope project my-first-server -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

This writes .mcp.json with absolute paths. Since .mcp.json is committed to git, swap them for ${CLAUDE_PROJECT_DIR} so the config works on any checkout:

{
  "mcpServers": {
    "my-first-server": {
      "type": "stdio",
      "command": "${CLAUDE_PROJECT_DIR}/.venv/bin/python",
      "args": ["${CLAUDE_PROJECT_DIR}/server.py"],
      "env": {}
    }
  }
}

• Verify: claude mcp get my-first-server (shows resolved absolute paths)

• Remove: claude mcp remove my-first-server --scope project

• First load of a project's .mcp.json prompts for approval

Trying it out

Start a Claude Code session in this directory, type /mcp to confirm my-first-server is connected, then try:

• "Save a note called Groceries: milk, eggs, bread"

• "Search my notes for eggs"

• "Use the add tool to add 42 and 58"

Notes

• NOTES storage in server.py is in-memory only and resets on restart.

License

MIT