mcp-server-local

ppenumatsa1/mcp-server-local

3.1

If you are the rightful owner of mcp-server-local and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This repository contains a local MCP server that wraps a FastAPI-based customer API, exposing tools and resources over the stdio protocol for local integration.

MCP local server (customer)

This repository contains a local MCP (Mediated Chat/Tool) server that wraps a FastAPI-based customer API. The MCP server exposes tools and resources over the stdio protocol for local integration (for example, Claude Desktop).

Tech stack

  • Python 3.12
  • FastAPI (HTTP API) — backend/app
  • Uvicorn (ASGI server)
  • MCP (mcp package) for the tool/resource/prompt surface
  • httpx, pydantic, sqlmodel and other dependencies listed in backend/requirements.txt

See docs/ for design notes, project structure and feature breakdown.

Quick start (development)

  1. Create and activate a virtual environment in the repository root and install dependencies:
# Unix / macOS
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
# Windows (PowerShell)
py -3.12 -m venv .venv
# activate the venv in PowerShell
. .\.venv\Scripts\Activate.ps1
pip install -r backend\requirements.txt
  1. Configure environment variables. Copy the example file and edit backend/.env if you need to customize the API host/port or other settings:
cp backend/.env.example backend/.env
  1. Start the services you need for local development:
  • Start the FastAPI backend (serves the customer API on port 8000 by default):
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000
  • Start the MCP stdio server (used by Claude Desktop and tests):
python -m backend.mcp.mcp_stdio_server

Notes:

  • The stdio MCP server expects the HTTP API to be reachable (default: http://localhost:8000). Start the backend before running stdio tests or connecting Claude Desktop.

Claude Desktop Integration

Use this JSON snippet in your claude_desktop_config.json to register the local MCP server. The example below matches a typical Windows dev layout and uses an absolute path to the venv Python executable (adjust paths to your environment):

{
  "mcpServers": {
    "customer-mcp": {
      "command": "c:\\Projects\\code\\mcp-server-local\\backend\\.venv\\Scripts\\python.exe",
      "args": ["-m", "backend.mcp.mcp_stdio_server"],
      "cwd": "c:\\Projects\\code\\mcp-server-local",
      "env": {
        "PYTHONPATH": "c:\\Projects\\code\\mcp-server-local"
      }
    }
  }
}

After updating claude_desktop_config.json, restart Claude Desktop to connect to the local MCP server.

Running the bundled tests

These tests exercise the MCP stdio protocol and the customer API. Ensure the FastAPI backend is running (port 8000) before running the stdio tests.

  • Run the whole file with pytest:
pytest -q backend/tests/test_userflow_mcp.py
  • Run an individual stdio test (examples):
pytest -q backend/tests/test_userflow_mcp.py::test_get_customer_by_id_returns_customer_shape
pytest -q backend/tests/test_userflow_mcp.py::test_search_customers_returns_list
pytest -q backend/tests/test_userflow_mcp.py::test_list_orders_for_customer_returns_orders
  • You can also run the test script directly (simple convenience runner):
python backend/tests/test_userflow_mcp.py

More documentation

Project design, user flows and technical notes live in docs/design/.

Troubleshooting (stdio / tests)

  • Server returns "Received request before initialization was complete": ensure your client sends the LSP-style initialize request followed by a notifications/initialized notification before calling tools. Tests in backend/tests follow this pattern.

  • ClosedResourceError or partial responses in tests: this happens when the test process closes stdin/stdout too early. The test helper _run_messages_and_collect now reads output and waits for the expected response id before closing stdin; if you still see issues, increase the pytest timeout or run the backend and MCP server manually during debugging.

  • No HTTP response from backend: confirm the FastAPI app is running on the expected host/port (default: http://localhost:8000) and that API_BASE in backend/.env matches.

  • Claude Desktop cannot connect: verify the claude_desktop_config.json entry points to the exact Python executable inside your venv and that cwd is the repo root. Restart Claude Desktop after changes.

  • Useful debug tips:

    • Run the backend (uvicorn) and then start the MCP stdio server in a separate terminal to watch logs directly.
    • Use the test runner examples in backend/tests to replicate issues quickly.
    • If tests intermittently fail, re-run with -k <testname> -s to see live stdout/stderr from the server.