Local 3GPP MCP Server

A small local Model Context Protocol server that extracts and serves 3GPP specification PDFs from disk. The model remains in your MCP client; this server makes no external API calls at query time.

Requirements and setup

• Python 3.11 or newer

• A local checkout of the curated 3GPP documents

Clone the document repository yourself (the server intentionally does not do this automatically):

git clone https://github.com/emanuelfreitas/3gpp-documentation.git

Create a virtual environment and install the two runtime dependencies:

cd /full/path/to/3gpp-local-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Run

Set SPECS_DIR to the cloned repository's documentation directory. The default is ./documentation relative to the process working directory.

SPECS_DIR=/full/path/to/3gpp-documentation/documentation python server.py

The initial run extracts every readable PDF and writes .cache/index.json. Later starts reuse cached text for files whose path, modification time, and size have not changed. Corrupt, scanned, and empty PDFs are logged and skipped.

Force a complete rebuild with python server.py --rebuild, or call the MCP refresh_index tool. Optional Streamable HTTP mode is available at http://127.0.0.1:8000/mcp:

SPECS_DIR=/full/path/to/documentation python server.py --http

You can also set MCP_TRANSPORT=http, MCP_HOST, and MCP_PORT. Stdio is the default and is appropriate for desktop MCP clients.

Tools

• list_specs() returns sorted, human-readable spec IDs.

• search_specs(query, max_results=5) performs case-insensitive keyword search and returns the first context snippet from each matching spec.

• get_spec(spec_id, max_chars=8000) returns extracted text, truncated to the requested limit.

• refresh_index() forces all PDFs to be re-extracted.

Client configuration

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "3gpp-local": {
      "command": "/full/path/to/3gpp-local-agent/.venv/bin/python",
      "args": ["/full/path/to/3gpp-local-agent/server.py"],
      "env": {
        "SPECS_DIR": "/full/path/to/3gpp-documentation/documentation"
      }
    }
  }
}

All paths must be absolute. The configured Python interpreter must be the one where fastmcp and pypdf are installed—normally the virtual environment shown above. Cursor uses a near-identical MCP server configuration.

Verify

The self-contained test suite creates a small text PDF and a corrupt PDF in a temporary directory; it does not require the document repository:

python -m unittest -v test_server.py

For a real-data smoke test, start the server with SPECS_DIR pointing at the curated checkout and confirm the startup log reports a non-zero indexed count.

Future phases

Potential upgrades include local semantic/vector search, live 3GPP or ETSI fetching, and section-aware pagination for very large specs. The v1 tool signatures can remain stable when those capabilities are added.