Mercury MCP Server

A Model Context Protocol (MCP) server exposing three tools to any MCP-compatible host (Claude Desktop, Cursor, etc.). It runs as a local Python process over stdio — no database, no REST API, no Docker Compose, no separate frontend.

Overview

The server exposes three tools:

Configuration is done entirely via environment variables (optionally loaded from a .env file).

SDK note: the mcp Python SDK removed the low-level @app.list_tools() / @app.call_tool() decorator API in 2.x. This project uses the current low-level mcp.server.Server API, passing the handlers as on_list_tools / on_call_tool constructor arguments. The three tool names, descriptions, and input schemas are identical to the design. (FastMCP was also renamed to MCPServer in 2.x.)

Related MCP server: Google Search MCP Server

Requirements

• Python 3.11+

• pip

Setup

Create and activate a virtual environment, then install the package with its dependencies:

# from the project root (this directory)
python -m venv .venv

# activate: Windows (Git Bash / cmd)
source .venv/Scripts/activate
# activate: macOS / Linux
# source .venv/bin/activate

# install the package in editable mode (installs mcp, requests, python-dotenv, pytest)
pip install -e ".[dev]"

[dev] includes pytest. If you did not install with the dev extra, run pip install pytest and pip install -e . separately.

Optional: copy the environment template and fill in your keys:

cp .env.example .env

Environment variables

Running the server

Run the stdio server directly:

python -m mercury_mcp.server

or via the installed console script:

mercury-mcp

Because it is an MCP stdio server it is normally launched by your MCP host rather than run interactively. See MCP server config below.

The three tools

surf_sense_search

Live web search via SurfSense. When SURFSENSE_API_KEY and SURFSENSE_WORKSPACE_ID are both set it performs a real scrape; otherwise it returns deterministic mock data.

Input schema: query (required string) and connector (optional, default google_search, one of google_search, reddit, youtube, web_crawl, amazon, walmart, google_maps, indeed, tiktok, instagram).

{
  "query": "latest AI news",
  "connector": "google_search"
}

Output: JSON with source, query, and items (each item has title and content).

ghost_pepper_process

Process a transcript or arbitrary text. If text is empty, it reads the most recently modified .md file in GHOST_PEPPER_TRANSCRIPT_DIR.

Input schema: text (optional string).

{
  "text": "We discussed AI trends and new features. The roadmap is approved. Next step is rollout."
}

Output: JSON with headlines (up to 3 sentences), word_counts, top_terms (up to 5 keyword/count pairs), and the full transcript.

hermes_3d_visualize

Turn processed data into a 3D office visualization. When HERMES3D_ENABLED=true it returns an HTML <iframe> pointing at HERMES3D_OFFICE_URL; otherwise it returns a short text summary.

Input schema: data (required object, e.g. the result of ghost_pepper_process).

{
  "data": { "headlines": ["We discussed AI trends", "Roadmap approved"] }
}

Output: iframe HTML or a text string.

Tests

pytest -q

MCP server config (section 8)

Add the server to your MCP client configuration. Example for openmausbot:

{
  "mcpServers": {
    "mercury": {
      "command": "python",
      "args": ["-m", "mercury_mcp.server"],
      "env": {}
    }
  }
}

Use the full path to your venv's Python if python is not on the host's PATH. For instance, on Windows the venv interpreter is typically: .venv/Scripts/python.exe under the project root. You can also inject environment variables via the "env" block, or rely on the .env file (loaded automatically on startup).

Project layout

.
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/
│   └── mercury_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── config.py
│       └── tools/
│           ├── __init__.py
│           ├── surfsense.py
│           ├── ghostpepper.py
│           └── hermes3d.py
├── tests/
│   ├── test_surfsense.py
│   ├── test_ghostpepper.py
│   └── test_hermes3d.py
└── examples/
    └── openmausbot_mcp_config.json