3gpp-kb-mcp

Self-contained MCP server for 3GPP telecom specifications.

Gives any MCP-compatible AI assistant (Cursor, Claude Desktop, VS Code Copilot) semantic search over 3GPP Technical Specifications (TS) and Technical Reports (TR) — no Python, no server, no internet required at query time.

Quick Start

Step 1 — Build the local SQLite database (one-time)

# Clone the pipeline and build your knowledge base
git clone https://github.com/your-repo/3gpp-kb
cd 3gpp-kb

# Install and run the full pipeline (downloads + extracts + embeds ~997 specs)
pip install -r requirements.txt
python pipeline.py run-all          # builds 3gpp_kb/chunks/ and ChromaDB index

# Export to SQLite for standalone use
python export_to_sqlite.py          # creates 3gpp_kb/3gpp.db (~400 MB)

One-time only. After this, no Python needed — ever.

Step 2 — Add to Cursor / Claude Desktop

{
  "mcpServers": {
    "3gpp-kb": {
      "command": "npx",
      "args": ["3gpp-kb-mcp@latest", "--db", "/absolute/path/to/3gpp_kb/3gpp.db"]
    }
  }
}

First run downloads the embedding model (~25 MB) and caches it. After that, fully offline.

Step 3 — Ask questions

"What are the beam management procedures in 5G NR?"
"Show me TS 38.331 RRC reconfiguration procedure"
"Explain AMF registration in TS 23.501"
"List all security specs in series 33"

CLI Usage

# Standalone (no server needed)
npx 3gpp-kb-mcp --db /path/to/3gpp_kb/3gpp.db

# Proxy mode (requires Python FastAPI backend)
npx 3gpp-kb-mcp --api-url http://localhost:8000

# Help
npx 3gpp-kb-mcp --help

Available Tools

| Tool | Description | |------|-------------| | search_3gpp | Semantic search across all specs. Filter by series, release, doc_type | | get_spec_info | Full text of a specific spec (e.g. 38.331, 23.501) | | list_specs | Browse indexed specs, filterable by series or release | | list_series | 3GPP series catalog — which series are indexed | | kb_stats | Chunk count, specs, model, mode (standalone vs proxy) |

Architecture

MCP Client (Cursor / Claude)
    │ stdio
    ▼
3gpp-kb-mcp  (this package)
    │
    ├── STANDALONE MODE (default)
    │     Transformers.js — all-MiniLM-L6-v2 (runs in Node.js, 25MB model)
    │     better-sqlite3  — local 3gpp.db (~400MB, pre-computed embeddings)
    │     Pure JS cosine similarity — no external services
    │
    └── PROXY MODE (--api-url)
          HTTP → FastAPI backend (pipeline.py serve)
          ChromaDB + sentence-transformers (Python)

Version History

| Version | What changed | |---------|-------------| | v2.0.0 | Standalone mode — runs entirely in Node.js, no Python/server required | | v1.0.x | Proxy mode only — required Python FastAPI backend |

License

MIT