Skip to main content
Glama
seven0070

Mercury MCP Server

by seven0070
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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:

Tool

Purpose

surf_sense_search

Live web research via the SurfSense REST API (with a mock fallback when not configured).

ghost_pepper_process

Local transcript / text processing — extracts headlines, word count, and top keywords.

hermes_3d_visualize

3D office visualization — returns an iframe URL when enabled, otherwise a text summary.

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

Variable

Default

Description

SURFSENSE_API_URL

https://api.surfsense.com

Base URL of the SurfSense API.

SURFSENSE_WORKSPACE_ID

""

SurfSense workspace ID (required to enable live search).

SURFSENSE_API_KEY

""

SurfSense API key. surf_sense_search uses a mock fallback when this is empty.

GHOST_PEPPER_TRANSCRIPT_DIR

""

Directory of .md transcript files for ghost_pepper_process.

HERMES3D_ENABLED

false

When true, hermes_3d_visualize returns an iframe; otherwise a text summary.

HERMES3D_OFFICE_URL

http://localhost:3000/office

URL embedded in the iframe.

LOG_LEVEL

INFO

Logging level.

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

Available Tools

3 tools
ghost_pepper_processA

Process a transcript or text and extract headlines, word count, and keywords

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoTranscript text (if empty, reads latest from configured directory)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the output artifacts (headlines, word count, keywords) but does not state whether it is read-only, what permissions or config it depends on, or how large inputs are handled. Adequate but with clear behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence that front-loads the verb, resource, and output. No filler and nothing that fails to earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter tool with no output schema, the description covers the input forms (transcript or text) and the return contents (headlines, word count, keywords). It omits output format and behavioral caveats, but is largely complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter and schema description coverage is 100%; the schema already explains that an empty 'text' reads the latest from the configured directory. With 0 required parameters, the baseline is 4, and the description adds no contradictory or redundant parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('process') plus a concrete resource ('transcript or text') and enumerates exactly what it extracts: headlines, word count, and keywords. Distinct from the siblings (a search tool and a visualization tool), so an agent can differentiate without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The schema note that an empty text 'reads latest from configured directory' implies a default usage path, but the description itself gives no when-to-use, when-not-to-use, or alternative guidance. Usage is only loosely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_3d_visualizeC

Generate a 3D visualization (iframe) from processed data

ParametersJSON Schema
NameRequiredDescriptionDefault
dataYesProcessed data JSON (as returned by ghost_pepper_process)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations and no output schema, the description carries the full behavioral burden, yet it only hints that the result is an iframe. It does not disclose whether it returns HTML/URL, renders inline, writes a file, requires specific permissions, or has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity comes at the cost of the behavioral detail noted elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a nested object parameter, no annotations, and no output schema, the description is too thin. It does not explain the return value or rendering behavior, leaving the agent without enough context to invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter with 100% schema description coverage, so the schema already documents it. The description adds marginal value by indicating the data should be 'processed' output, but gives no format or structural detail beyond what the schema and its note (ghost_pepper_process) provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: generate a 3D visualization from processed data, and even names the output format (iframe). It does not explicitly differentiate itself from siblings like ghost_pepper_process, though 'from processed data' implies the pipeline order.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or mention of alternatives. The phrase 'from processed data' weakly implies the prerequisite that data must first be processed, but nothing states when this tool should or should not be chosen.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedghost_pepper_process
    • First observedhermes_3d_visualize
    • First observedsurf_sense_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct action: web search, transcript/text processing, and 3D visualization. There is no functional overlap between them, so an agent will not confuse surf_sense_search with ghost_pepper_process or hermes_3d_visualize.

Naming Consistency4/5

All three follow a consistent <brand>_<action> snake_case pattern (surf_sense_search, ghost_pepper_process, hermes_3d_visualize), which is predictable. However the opaque brand prefixes (ghost_pepper, hermes) reduce readability and hint at product-specific naming rather than a clean verb_noun convention.

Tool Count4/5

Three tools is on the thin side but each maps to a distinct stage of a search -> process -> visualize pipeline, so none feels redundant. It is reasonable for a focused media/analysis server, though slightly under-scoped for standalone use.

Completeness3/5

The set implies a pipeline (search, process, visualize) but lacks ways to retrieve or persist intermediate results, configure the pipeline, or manage prior runs. Core stages exist but there are notable gaps that could force agents to work around missing operations.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers