Skip to main content
Glama

3gpp-mcp

Go Reference Go Report Card CI codecov GitHub Release

An MCP (Model Context Protocol) server that makes 3GPP specifications accessible to LLMs.

Background

3GPP specifications are essential references for mobile and telecommunications engineering, but they are difficult for LLMs to work with effectively:

  • Too many documents - Thousands of specifications exist across multiple series, making it hard to find the right one.

  • Individual documents are too large - Many specs are hundreds of pages long, far exceeding typical context windows.

  • Distributed as Word files - Specs are published in .docx / .doc format and require conversion for text processing.

  • Heavy cross-referencing - Specs frequently reference each other; reading a single document in isolation gives an incomplete picture.

  • Information packed in tables and figures - Complex tables and flow diagrams carry critical details. This tool converts tables to Markdown and extracts embedded images for LLM viewing.

  • Version complexity - The same specification exists across multiple 3GPP releases, and identifying the correct version matters.

This tool addresses these challenges by parsing the .docx files, structuring the content by section, and storing everything in a SQLite database with full-text search (FTS5). An MCP server then exposes tools for searching, browsing by section, and following cross-references — letting an LLM navigate the specifications the way an engineer would.

Why not RAG?

Embedding-based RAG is a common way to improve accuracy on document Q&A, and RAG systems specialized for 3GPP documents exist (Telco-RAG, TelcoAI). This tool takes a simpler approach: instead of building a retrieval pipeline in front of the model, it gives the model search and navigation tools and lets it explore the specifications the way an engineer would — full-text search, then following the section hierarchy and cross-references. Since retrieval is plain FTS5 search over structured sections, there is no embedding model or vector database to run, and everything lives in a single SQLite file.

Measured on TeleQnA, this lifts accuracy on 3GPP standards questions by 6.5 to 12.0 percentage points across three model families. Most of that is having the text at all: a single BM25 query over the same database accounts for +7.8 to +9.6pt of it. The tool's own search is what separates them on questions whose answer sits more than one hop from the first retrieved passage — on tasks generated from the specifications themselves (protocol codes, ASN.1 structure, 5G SBI schemas) it answers and correctly cites 88-100%, beating that same BM25 baseline by +26 to +88 points on every task type and every model. See BENCHMARK.md.

Related MCP server: mcp-docs

Getting Started

1. Install

# Homebrew
brew install higebu/tap/3gpp-mcp

# ...or with Go 1.26+
go install github.com/higebu/3gpp-mcp/cmd/3gpp-mcp@latest

Prebuilt binaries are also available on the releases page. LibreOffice is optional (needed for .doc to .docx conversion and EMF/WMF image to PNG conversion).

2. Build the database

Download and import specifications into the database. Temporary files are deleted after each spec is processed, minimizing disk usage.

# Download and import the latest version of every spec (all releases)
3gpp-mcp build --latest --db data/3gpp.db --convert-doc --convert-image

# ...or restrict to a single release
3gpp-mcp build --release 19 --db data/3gpp.db --convert-doc --convert-image

This will scrape the 3GPP FTP archive, download ZIP files, extract and parse .docx files, and insert structured content into the SQLite database.

3. Register with your MCP client

Claude Code

claude mcp add --scope user 3gpp -- 3gpp-mcp serve --db /path/to/data/3gpp.db

VS Code / GitHub Copilot

code --add-mcp '{"name":"3gpp","command":"3gpp-mcp","args":["serve","--db","/path/to/data/3gpp.db"]}'

GitHub Copilot CLI

Add to ~/.config/github-copilot/cli-mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "3gpp": {
      "command": "3gpp-mcp",
      "args": ["serve", "--db", "/path/to/data/3gpp.db"]
    }
  }
}

Codex CLI

codex mcp add --name 3gpp --command 3gpp-mcp --args serve --db /path/to/data/3gpp.db

Claude Desktop

Add to your configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "3gpp": {
      "command": "3gpp-mcp",
      "args": ["serve", "--db", "/path/to/data/3gpp.db"]
    }
  }
}

4. Web viewer (optional)

Browse specifications in your browser by adding --web to the HTTP transport:

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080 --web
# MCP endpoint: http://localhost:8080/mcp/
# Web viewer:   http://localhost:8080/

Features: spec list with filtering, section viewer with TOC sidebar, full-text search with pagination, past-version browsing (versions are listed per spec and downloaded on demand, like the MCP tools), version comparison (structural summary and per-section diffs), embedded images, meeting lists and documents (TDocs) fetched on demand at /meetings and /tdocs, cross-reference links, OpenAPI definitions with syntax highlighting, KaTeX rendering of the LaTeX formulas the converter emits, dark mode, responsive design. Code blocks are syntax-highlighted per notation — ASN.1, Diameter, SIP/RTSP, SDP and XML (see Code blocks).

WebMCP

When the browser provides the W3C WebMCP API (document.modelContext, a Chrome origin trial as of 2026), the viewer registers all of its MCP tools with the browser at page load, so an in-browser agent can query the spec database directly. The registration is a thin same-origin passthrough to the /mcp/ endpoint — there is nothing to configure server-side, and browsers without the API are unaffected. During the origin trial, enable it locally via Chrome flags (chrome://flags), or for a shared deployment serve an Origin-Trial header from a fronting proxy.

Deployment

Streamable HTTP

The HTTP transport is stateless: it supports MCP protocol version 2026-07-28 (no initialize handshake, no Mcp-Session-Id) while older clients (2024-11-05 through 2025-11-25) keep working through per-request sessions.

Start the server with HTTP transport:

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

Optionally enable Bearer token authentication:

export THREEGPP_MCP_BEARER_TOKEN=$(openssl rand -hex 32)
3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

Then configure your client to connect via HTTP:

{
  "mcpServers": {
    "3gpp": {
      "url": "http://your-server:8080",
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_TOKEN"
      }
    }
  }
}

When using --web, the MCP endpoint moves to /mcp/.

See examples/systemd/ for production deployment with systemd.

Docker

The Dockerfile is multi-stage and builds the database for a release directly, producing a self-contained image with the SQLite database (sections, OpenAPI definitions, and embedded images) baked in. No pre-built database is needed in the build context.

# Build an image with the latest version of every spec baked in (default)
docker build -t 3gpp-mcp:latest .

# ...or restrict the database to a single release
docker build --build-arg RELEASE=19 -t 3gpp-mcp:rel19 .

# ...or cap the newest release, keeping specs that have no version in it
docker build --build-arg MAX_RELEASE=19 -t 3gpp-mcp:max-rel19 .

# stdio transport (Claude Code / IDE integration)
docker run --rm -i 3gpp-mcp:latest

# HTTP transport
docker run --rm -p 8080:8080 3gpp-mcp:latest serve --db /3gpp.db --transport http --addr :8080

RELEASE defaults to latest, which bakes in the latest version of every spec across all releases. Set --build-arg RELEASE=<n> (e.g. 19) to restrict the database to a single release, or --build-arg MAX_RELEASE=<n> to cap the newest release without dropping specs that have no version in it. The two cannot be combined.

Cloud Run

To run on Cloud Run, see cloudbuild.yaml (build + push + deploy) and service.yaml (Cloud Run service spec).

Tools

Every tool below also has a CLI twin (list_specs → 3gpp-mcp list-specs, and so on) for shell use and scripting — see the query commands in the Command Reference.

Browsing specifications

Tool

Description

Key Parameters

list_specs

List available specifications (paginated)

series (optional): filter by series number, e.g. "23"; query (optional): spec ID prefix, e.g. "38.21"; limit, offset

list_versions

List the versions of a spec and where each can be read from

spec_id (required): e.g. "TS 23.501"

get_toc

Get table of contents of a spec

spec_id (required), version

get_section

Get section content (paginated)

spec_id, section_number (required), version, include_subsections, offset, max_lines, max_chars

compare_versions

Compare two versions of a spec: structural summary, or a section text diff

spec_id, old_version (required), new_version, section_number, include_subsections, context_lines, offset, max_lines, max_chars

Every get_toc, get_section and search result names the specification and version it came from, on every page of a paginated response.

Past versions

The database holds one version per specification. To read another version, pass version to get_section or get_toc. version accepts the dotted form (15.8.0), the archive token (f80), a release selector (Rel-15 or 15, picking the newest version in that release), or latest. Release selectors and latest are resolved against the 3GPP archive, so they require on-demand fetching (they do not work under --no-fetch). old_version and new_version of compare_versions accept the same forms; new_version defaults to the version in the database.

A version that is not in the database is downloaded from the 3GPP archive and converted on first use. This takes up to a few minutes for a large specification; if it is still running when the call's budget expires, the tool says so and the same call repeated later returns the content. Results are kept in a size-bounded cache (see serve) that is separate from the main database, so:

  • search covers only the version in the database — cross-release full-text search is not supported

  • get_references only has data for the version in the database, and a section read from an archived version says so in its header

  • get_image and list_images accept a version too: an archived version's images are downloaded on their own first use (one extra archive download per version, with the same retry behavior), and EMF/WMF figures are converted to PNG when LibreOffice is installed on the server

  • section numbers move between releases; check get_toc for the older version before reading a section of it

Searching

Tool

Description

Key Parameters

search

Full-text search across all specs

query (required), spec_ids (optional), limit, offset

The search tool supports SQLite FTS5 query syntax:

  • Phrase search: "service based interface"

  • Boolean operators: AMF AND UE, AMF OR SMF, NOT deprecated

  • Exclusion after a positive term: handover -conditional

  • Prefix matching: handov*

  • Column filter: title:authentication, content:handover

  • Proximity: NEAR(AMF UE, 5)

Terms containing hyphens or dots (IMS-AKA, 38.101) are quoted automatically, so they need no manual escaping.

Cross-references

Tool

Description

Key Parameters

get_references

Get cross-references between specs and RFCs

spec_id (required), section_number (required for "outgoing"), direction ("outgoing" or "incoming"), include_subsections, offset

OpenAPI definitions

Tool

Description

Key Parameters

list_openapi

List available OpenAPI definitions

spec_id (optional): filter by spec, e.g. "TS 29.510"

get_openapi

Get OpenAPI definition (paginated)

spec_id, api_name (required), path, schema, offset, max_lines

search_openapi

Full-text search across OpenAPI definitions

query (required), spec_ids, api_name, kind ("schema" or "operation"), include_body, limit, offset

search_openapi uses its own FTS5 index, separate from the one search uses: search covers specification clause text and never returns OpenAPI content, search_openapi covers OpenAPI content only. One hit is one definition rather than one document — a schema from components.schemas, or one HTTP method of one path (named like PUT /nf-instances/{nfInstanceID}) — so you can find a data type or an endpoint without knowing which API document defines it, then read it in full with get_openapi. A query that is a single bare term ranks a definition of exactly that name first, so NFProfile returns the NFProfile schema ahead of the schemas that only reference it.

A schema's indexed text carries one level of $ref expansion — through items and additionalProperties as well as directly, which is how the 5G SBI definitions state most of their relationships — so the fields of a referenced type are searchable from the schema that uses it; a type two hops away is not in that text. Unlike search, this index applies no stemming — identifiers are matched as written — and -, . and _ split tokens, so Nnrf_NFManagement is also found by NFManagement and /nf-instances by instances. camelCase is not split.

The index is built at the end of build and update. import and import-dir leave it alone: the YAML files ship in the archive zip, so importing a .docx cannot change what there is to index. A database built before this tool existed has no index; add it in place with build-openapi-index.

ASN.1 definitions

Tool

Description

Key Parameters

get_asn1

Get an ASN.1 assignment by name — in one spec or across all of them — or list a spec's assignment names

spec_id (optional; omit to resolve name across every spec), name (assignment name, e.g. AMF-UE-NGAP-ID; required without spec_id), version (requires spec_id), offset, max_lines, max_chars

The ASN.1-specified protocols (RRC TS 38.331/36.331, NGAP TS 38.413, S1AP TS 36.413, XnAP, F1AP, ...) write their ASN.1 between -- ASN1START / -- ASN1STOP markers, which the converter stores as ```asn1 fences (see Code blocks). get_asn1 extracts every top-level assignment — types, constants and information objects — from those fences.

With name it returns that assignment's full text together with the section that defines it, so the answer can be cited. This matters for the protocols that define all their IEs in one clause: NGAP's IE definitions clause is hundreds of kilobytes, far more than one get_section page, while the one definition that answers "what range does the ASN.1 allow here" is a few lines. Matching ignores case and separators, so the IE table's AMF UE NGAP ID finds the ASN.1's AMF-UE-NGAP-ID; a name that matches nothing gets similar names suggested. A name defined more than once returns every definition, each under its own source line.

When you do not know which specification defines a name, omit spec_id: the name is resolved across every specification in the database, from a name index built at database build time (build, update, import and import-dir all refresh it). A lookup that names the wrong specification gets told where the name is actually defined. A database built before this tool existed has no index — add it in place with build-asn1-index. Cross-spec resolution covers the database versions only — pass spec_id (and optionally version) to read an archived version, with the same on-demand download behavior as get_section.

With a spec_id and no name it lists every assignment name, grouped by defining section.

Embedded images

Tool

Description

Key Parameters

list_images

List embedded images in a spec

spec_id (required), version (optional)

get_image

Get an embedded image as base64 data viewable by LLMs

spec_id, name (required): image filename, version (optional)

PNG/JPEG/GIF/WebP images are directly viewable by LLMs. EMF/WMF images (most 3GPP figures use this format) are stored as raw data by default; use --convert-image to convert them to PNG via LibreOffice at build time.

Figures are referenced from the section text in a single notation, whatever the image format: ![Figure](image://NAME?w=&h=) in body text and <img src="image://NAME?w=&h=" ...> inside table cells. Pass that NAME to get_image; both the original filename (image3.emf) and the converted one (image3.png) resolve.

Meeting documents (TDocs)

Tool

Description

Key Parameters

list_meetings

List a group's meetings, newest first, with codes, dates, TDoc ranges and FTP folders; without a group, the supported groups

group (R1, RAN1, SA2, ...), limit, offset (all optional)

list_tdocs

List a meeting's documents from its official TDoc list, with type, status, source, agenda item, title and CR/LS details

meeting (required): R1-123, RAN1#123 or the folder path; group, agenda_item, type, status, source, spec, query, details, limit, offset (all optional)

get_tdoc

Read a meeting document (TDoc) as Markdown

tdoc_id (required): TDoc number (R1-2509715) or an FTP path (tsg_ran/WG1_RL1/TSGR1_123/Report/Final_Minutes_report_RAN1#123_v100.zip), meeting, section_number, offset, max_lines, max_chars (all optional)

get_meeting_report

Read a meeting's report (minutes) or final agenda by meeting name

meeting (required); group, kind (report, default, or agenda), section_number, offset, max_lines, max_chars (all optional)

TDocs are the working documents of a 3GPP meeting: contributions, change requests (CRs), liaison statements (LSs), agendas and meeting reports. A TDoc number is located through the group's DynaReport meeting page (https://www.3gpp.org/dynareport?code=Meetings-R1.htm and its siblings) by TDoc number range, downloaded from that meeting's Docs/ folder and converted on first use. Pass meeting (R1-123, RAN1#123, TSGR1_123) when the number falls in no listed range. A document with no TDoc number — a meeting report, for instance — is named by its path under https://www.3gpp.org/ftp/ instead.

list_tdocs lists a meeting's official TDoc list: every document's type, status (agreed, noted, revised, ...), source, agenda item, revision chain, and for a CR the spec, CR number and category, for an LS the addressees. Without filters the output opens with the agenda items and their document counts; query is a full-text search over titles, sources, abstracts, agenda item descriptions and work items, scoped to that meeting. The list is refreshed daily while the meeting is recent.

Converted documents and TDoc lists are kept in their own size-bounded cache (tdocs.db, see --tdoc-cache), separate from the main database: TDocs are never imported into it and search does not cover them.

get_meeting_report reads a meeting's approved report or final agenda by meeting name alone; the output header names the document it resolved to, and the sections carry the numbers the document shows, so an agenda item's section can be read by number.

Notes:

  • A CR's cover sheet and an LS's header are in the section named preamble, and summarized at the top of the output: for a CR the spec, CR number, category, release, source, reason for and summary of the change, the clauses affected, and the get_section call that reads a changed clause at the version the CR is written against; for an LS the sender, addressees, the LS it replies to, release, work item and contact. The web viewer shows the same block and links each changed clause, and each numbered section of the CR, to the spec.

  • A download that holds attachments has only its main Word file converted; the others are listed in the output header so a reader knows they exist.

  • .doc documents need LibreOffice (soffice) at runtime; .pptx, .xlsx and .pdf are not converted and the tool reports the file list instead.

  • Supported groups: RAN and RAN1-6, SA and SA1-6, CT and CT1, CT3, CT4, CT6, and GERAN — TDoc prefixes RP, R1-R6, SP, S1-S6, CP, C1, C3, C4, C6 and GP.

Code blocks

Section text carries tagged code fences, so both LLMs and the web viewer can tell the notations apart:

Fence

Content

```asn1

ASN.1 modules between the -- ASN1START / -- ASN1STOP markers

```diameter

Diameter command and grouped-AVP definitions (RFC 6733 CCF)

```xml

XML schemas, XML body examples and DTDs

```sip

SIP/RTSP message examples

```sdp

Standalone SDP session descriptions

```latex

Standalone equations converted from Word OMML

```

Anything else the source document styles as code

Formulas

Word formulas (OMML) are converted to LaTeX in three notations, so a formula is readable whether it stands alone or sits in a sentence:

Notation

Where

```latex fence

A paragraph whose only content is an equation. Its equation number is kept as \tag{7.3-1}, which renders as a right-aligned (7.3-1).

$$...$$

Display equations that cannot be a fenced block — inside a table cell or a list item.

$...$

A formula inside a sentence.

Indentation

3GPP prose encodes structure in indentation — nested requirement and condition lists, multi-level definitions. A body paragraph's leading whitespace is preserved as no-break spaces (U+00A0), one tab of the source document becoming four: a literal tab or 4+ leading spaces would turn the line into an indented code block in Markdown (inside which HTML like <sub> is never interpreted), while no-break spaces keep the visual nesting in any renderer and stay out of the way of full-text search.

Tips

Tell the model to use the tools

Attaching the server does not by itself make a model consult it: given the choice, some models answer 3GPP questions from memory. In the benchmark, Claude Sonnet 5 skipped retrieval on 40% of TeleQnA questions and GPT 5.6 Luna on 60%, and on those questions the tools were worth nothing. One sentence in the client's system prompt removes that discretion. The measured wording:

Do not answer from memory. Search the specifications first and base your answer on the text you retrieve, even when you are confident you already know the answer.

That sentence took Luna's skip rate to zero and its gain from +5.9 to +12.0 points, moved nothing on a model that already searched every question, and is worth nothing without the tools attached — it forces retrieval rather than smuggling in an answer. Stronger house rules in the same spirit — base every answer about 3GPP on clause text retrieved through these tools, and cite the clause — are reasonable, but only the sentence above is what the benchmark measured.

Separate databases per release

For spot comparisons across releases, compare_versions and the version parameter need no extra setup. Building a separate database per release still pays off when you work against one release continuously: full-text search, get_references and OpenAPI definitions only cover the version baked into the database, so a release-specific database gives you all three for that release, with no on-demand downloads.

# Build databases for different releases
3gpp-mcp build --release 18 --db data/3gpp-rel18.db --convert-doc --convert-image
3gpp-mcp build --release 19 --db data/3gpp-rel19.db --convert-doc --convert-image

--release keeps only specs that have a version in that exact release, so a spec frozen in an earlier release (TS 34.108, for example) is missing from the database entirely. To pin a release without losing those specs, cap the selection instead — every spec is taken at its newest version at or below the cap:

# Everything as of Release 19: specs with no Rel-19 version fall back to their
# newest older version rather than dropping out.
3gpp-mcp build --max-release 19 --db data/3gpp-rel19.db --convert-doc --convert-image

# Keep the cap when refreshing the database later.
3gpp-mcp update --max-release 19 --db data/3gpp-rel19.db --convert-doc

Register them as separate MCP servers:

claude mcp add --scope user 3gpp-rel18 -- 3gpp-mcp serve --db /path/to/data/3gpp-rel18.db
claude mcp add --scope user 3gpp-rel19 -- 3gpp-mcp serve --db /path/to/data/3gpp-rel19.db

Keeping specs up to date

Use the update command to check for newer versions of specs already in your database:

3gpp-mcp update --db data/3gpp.db --convert-doc --convert-image

Command Reference

serve

Start the MCP server.

Flag

Description

Default

--db

Path to SQLite database

3gpp.db

--transport

Transport type: stdio or http (env: THREEGPP_MCP_TRANSPORT; defaults to http when PORT is set)

stdio

--addr

HTTP listen address (env: THREEGPP_MCP_ADDR, or PORT interpreted as :$PORT)

:8080

--bearer-token

Bearer token for HTTP auth (env: THREEGPP_MCP_BEARER_TOKEN)

--web

Enable web viewer alongside MCP server (HTTP transport only)

false

--no-fetch

Disable on-demand fetching of spec versions that are not in the database

false

--version-cache

Path to the on-demand version cache

$XDG_CACHE_HOME/3gpp-mcp/versions.db (~/.cache/3gpp-mcp/versions.db when unset)

--version-cache-mb

Size limit of the version cache in MB. 0 keeps only the most recently fetched version, -1 is unlimited (env: THREEGPP_VERSION_CACHE_MB)

1024

--tdoc-cache

Path to the on-demand meeting document (TDoc) cache

$XDG_CACHE_HOME/3gpp-mcp/tdocs.db (~/.cache/3gpp-mcp/tdocs.db when unset)

--tdoc-cache-mb

Size limit of the meeting document cache in MB. 0 keeps only the most recently fetched document, -1 is unlimited (env: THREEGPP_TDOC_CACHE_MB)

512

--fetch-budget

How long a tool call waits for an on-demand fetch before asking the caller to retry (env: THREEGPP_FETCH_BUDGET)

60s

The version cache is a separate SQLite file, so the main database stays read-only and is never polluted with extra versions. The meeting document cache is a third file, bounded and evicted the same way; --no-fetch disables both. When the cache cannot be created — a read-only or ephemeral filesystem, such as the scratch-based container image — the server logs a warning and runs with on-demand fetching disabled; everything else keeps working. Cached versions are evicted least-recently-used once the size limit is exceeded.

HTTP transport also exposes GET /health, which returns 200 OK without authentication. Use this path for platform health checks (Cloud Run, Sakura AppRun, Kubernetes liveness/readiness probes, etc.).

build

Download and import specifications into the database (recommended for initial setup). Alias: pipeline.

Flag

Description

Default

--db

Output SQLite database path

3gpp.db

--release

Process specs for a specific release (e.g. 19)

--max-release

Cap the selection at a release (e.g. 19): take each spec at its newest version at or below it

--latest

Select every spec at its latest version (use when no other selector is given)

false

--spec

Process a specific spec (e.g. 23.501)

--series

Filter by series, comma-separated (e.g. 23,29)

--workers

Number of parallel workers

NumCPU

--convert-doc

Convert .doc files to .docx using LibreOffice

false

--convert-image

Convert EMF/WMF images to PNG using LibreOffice

false

--spec-list

Read the spec list from a file instead of scraping the archive (a selector is still required)

--no-cache

Disable the spec list cache

false

--scrape-workers

Concurrency for scraping spec listings (0 = auto)

0

--timeout

HTTP timeout

30s

One of --release, --max-release, --latest, --series or --spec must be given, --spec-list included: the file supplies the candidate entries and the selector filters them.

--release and --max-release differ in what happens to a spec that has no version in the named release: --release 19 drops it, --max-release 19 keeps it at its newest version below the cap. They cannot be combined.

Other commands

  • download — Download specifications without conversion (--output-dir, default specs). Requires one of --release, --max-release, --latest, --series or --spec, like build.

  • import — Import a single .docx file into the database. Alias: convert. Usage: 3gpp-mcp import --db data/3gpp.db path/to/spec.docx

  • import-dir — Import all .docx files in a directory into the database. Alias: convert-dir. Usage: 3gpp-mcp import-dir --db data/3gpp.db ./specs

  • update — Update specifications in the database to latest versions, or to a cap with --max-release.

  • build-openapi-index — Rebuild the OpenAPI search index of an existing database. build and update do this themselves, so it is for adding the index to a database built before search_openapi existed: serve opens the database read-only and cannot create it on the fly.

  • build-asn1-index — Rebuild the ASN.1 name index of an existing database. build, update, import and import-dir do this themselves, so it is for adding the index to a database built before get_asn1 existed.

  • completion — Print a shell completion script: 3gpp-mcp completion bash (or zsh, fish)

The cap is not stored in the database, so a database built with --max-release 19 needs the same flag on update — otherwise the update lifts every spec to the newest release on the archive. With a cap the update moves a spec in either direction, so it also brings an already-built uncapped database down to the cap; a spec whose every version is above the cap is removed, since no version of it belongs in a capped database. A spec missing from the archive listing is left untouched, as a failed listing looks the same as a withdrawn spec.

Query commands

The query commands (list-specs, list-versions, get-toc, get-section, get-asn1, compare-versions, search, list-openapi, get-openapi, search-openapi, get-references, list-images, get-image, list-meetings, list-tdocs, get-tdoc, get-meeting-report) mirror the MCP read tools 1:1, so the database can be inspected and scripted from a shell without an MCP client:

3gpp-mcp search --db data/3gpp.db --limit 3 "AMF AND authentication" | jq '.results[].section_number'
3gpp-mcp get-section --db data/3gpp.db "TS 23.501" 5.15.2 | less
3gpp-mcp list-tdocs --db data/3gpp.db --type CR --status agreed --spec 38.214 R1-123
3gpp-mcp get-tdoc --db data/3gpp.db R1-2509715 | less
3gpp-mcp get-meeting-report --db data/3gpp.db RAN1#123 | less

Conventions shared by all of them:

  • Flags must come before positional arguments.

  • JSON results print to stdout indented and unpaginated — pipe to jq, head or less. Warnings and progress notes go to stderr, so stdout stays parseable.

  • Commands that accept --version (and compare-versions) take the same version forms as the MCP tools (15.8.0, f80, Rel-15, latest) and wait for an on-demand download to finish instead of asking you to retry; interrupt with Ctrl-C. They share serve's fetch flags: --no-fetch, --version-cache, --version-cache-mb, --fetch-budget. Queries that name no version never create the version cache (list-versions reads an existing cache to report cached availability, but will not create one).

  • get-tdoc takes a TDoc number or an FTP path and an optional section (preamble for a CR cover sheet or an LS header), plus --meeting; list-meetings takes a group, list-tdocs a meeting with the same filters as the tool (--agenda-item, --type, --status, --source, --spec, --query, --details) and get-meeting-report a meeting, an optional section and --kind agenda for the agenda. The four share serve's meeting-document flags --no-fetch, --tdoc-cache, --tdoc-cache-mb and --fetch-budget and read their own cache only, never the version cache.

  • Every command takes --db (default 3gpp.db).

Environment Variables

Variable

Description

THREEGPP_MCP_TRANSPORT

Transport for serve (stdio or http); overridden by --transport

THREEGPP_MCP_ADDR

HTTP listen address for serve; overridden by --addr

THREEGPP_MCP_BEARER_TOKEN

Bearer token for HTTP transport auth

PORT

PaaS convention (Cloud Run / Heroku); serve defaults to HTTP transport on :$PORT

THREEGPP_VERSION_CACHE_MB

Size limit of the on-demand version cache in MB (default 1024)

THREEGPP_TDOC_CACHE_MB

Size limit of the on-demand meeting document (TDoc) cache in MB (default 512)

THREEGPP_FETCH_BUDGET

How long a tool call waits for an on-demand fetch (default 60s)

THREEGPP_MAX_ZIP_SIZE_MB

Max ZIP download size (default 512)

THREEGPP_CACHE_TTL_HOURS

Spec list cache TTL in hours (default 24)

THREEGPP_LISTING_RETRY_MS

Initial backoff between archive listing fetch attempts in ms (default 1000)

XDG_CACHE_HOME

Cache directory root, per the XDG Base Directory spec

Available Tools

13 tools
compare_versionsA

Compare two versions of a 3GPP specification. Without section_number, returns a structural summary: sections added, removed, renumbered, retitled, and whose content changed. With section_number, returns a line-level unified diff of that section's text. Use list_versions first to see which versions exist; a version not yet cached is downloaded and converted on first use — when the tool says a download is in progress, call it again with the same arguments.

Inputs: spec_id (required), old_version (required), offset, max_chars, +5 more.

get_asn1A

Get ASN.1 definitions from the 3GPP specifications. The protocol specifications (RRC TS 38.331/36.331, NGAP TS 38.413, S1AP TS 36.413, XnAP, F1AP, LPP TS 37.355, ...) write their ASN.1 between -- ASN1START / -- ASN1STOP markers, and this tool extracts every top-level assignment from those blocks. With name, it returns the full text of that assignment — type, constant or information object — together with the specification and section that define it, so the answer can be cited. Use it when you know a type, IE or constant name and need its definition or constraints: the defining clause can be hundreds of kilobytes, which get_section can only page through. If you do not know which specification defines the name, omit spec_id — the name is resolved across every specification in the database. Matching ignores case and separators, so an IE table title like 'AMF UE NGAP ID' finds AMF-UE-NGAP-ID. With a spec_id and no name, it lists every assignment name grouped by the section that defines it. Pass version (with spec_id) to read a past version, which is downloaded and converted on first use; call list_versions first to see which versions exist.

Inputs: name, offset, spec_id, version, +2 more.

get_imageA

Get an embedded image from a 3GPP specification. Returns the image as base64-encoded data that can be directly viewed by the LLM. Use list_images to discover available images for a spec. Pass version to read a past version's image; the images of an archived version are downloaded on first use, which takes up to a few minutes.

Inputs: name (required), spec_id (required), version.

get_openapiA

Get OpenAPI definition content for 5G service-based interface APIs (TS 29.xxx series). Use this tool to look up HTTP request/response details, API paths, parameters, request bodies, response schemas, and data type definitions. Use the path parameter to filter by API endpoint (e.g. /nf-instances) or the schema parameter to filter by data type (e.g. NFProfile). Use list_openapi first to discover available API names.

Inputs: spec_id (required), api_name (required), path, offset, +2 more.

get_referencesA

Get cross-references between 3GPP specifications and RFCs.

Directions:

  • outgoing (default): Find all specs/RFCs referenced by a given section. Requires spec_id and section_number. Use include_subsections to also gather refs from child sections.

  • incoming: Find all sections that reference a given spec (and optionally a specific section). Requires spec_id. section_number is optional.

Returns structured reference data including target spec, section, title (if available in DB), and context snippet. Responses are capped at 500 references; a separate notice reports the total, and offset pages through the rest.

Inputs: spec_id (required), offset, direction, section_number, +1 more.

get_sectionA

Get the markdown content of a specific section in a 3GPP specification. This tool is for reading specification document text (architecture, procedures, requirements). For API details such as HTTP request/response bodies, paths, and data models of 5G service-based interfaces (TS 29.xxx series), use get_openapi instead. Specify the section number with the section_number parameter (e.g. 5.1.2). Figures appear as ![...](image://NAME) links; fetch one with get_image and that NAME. Formulas are LaTeX: a standalone equation is a ```latex code block (its equation number kept as \tag{7.3-1}), and a formula inside a sentence or a table cell is delimited with $...$, or $$...$$ when the source sets it as a display equation. Pass version to read a past version, which is downloaded and converted on first use; call list_versions first to see which versions exist. Large sections are paginated (default 200 lines). Use offset and max_lines to navigate.

Inputs: spec_id (required), section_number (required), offset, version, +3 more.

get_tocA

Get the table of contents (section structure) of a 3GPP specification. Pass version to see the structure of a past version, which is downloaded and converted on first use; section numbers often move between releases, so check the table of contents before reading a section of an older version.

Inputs: spec_id (required), version.

list_imagesA

List embedded images in a 3GPP specification. Returns image names, MIME types, and whether they are viewable by LLMs. Use get_image to retrieve a specific image. Pass version to list a past version's images; the images of an archived version are downloaded on first use, which takes up to a few minutes.

Inputs: spec_id (required), version.

list_openapiA

List available OpenAPI definitions from 3GPP specifications (TS 29.xxx series). Use this to discover API names before calling get_openapi. Optionally filter by spec ID.

Inputs: spec_id.

list_specsA

List available 3GPP specifications. Optionally filter by series number and/or by an ID prefix (query). Results are paginated (default 20 per page); use limit and offset to navigate.

Inputs: limit, query, offset, series.

list_versionsA

List the versions of a 3GPP specification, newest first.

Each entry reports where the version can be read from:

  • database: in the prebuilt database, covered by search, images and cross-references

  • cached: fetched on demand earlier, available immediately

  • archive: exists upstream; reading it downloads and converts it first, which takes up to a few minutes for a large specification

Pass a version from this list to get_section or get_toc to read a past version.

Inputs: spec_id (required).

search_openapiA

Full-text search across the OpenAPI definitions of the 5G service-based interface APIs (TS 29.xxx series), using SQLite FTS5 syntax.

Use this when you need an API detail but do not know which API document holds it — searching for a data type (NFProfile, SmContextCreateData) or an endpoint (/nf-instances, subscriptions) finds it without guessing an api_name first. When you already know the document, get_openapi reads it directly.

This is a separate index from the search tool: search covers specification clause text and never returns OpenAPI content, and this tool covers OpenAPI content only.

Results:

  • One hit is one definition, not one document: either a schema (a data type from components.schemas) or an operation (one HTTP method of one path, named like "PUT /nf-instances/{nfInstanceID}").

  • A query that is a single bare term ranks a definition of exactly that name first, so searching NFProfile returns the NFProfile schema itself ahead of the schemas that merely reference it.

  • Each hit reports spec_id, api_name, kind, name and a snippet. Pass those to get_openapi (with its schema or path parameter) to read the full definition.

  • A schema's text carries one level of $ref expansion, so referenced field names are searchable, but a type two hops away is not. Follow it up with get_openapi.

  • Set include_body to get the matched definition's full text inline. It is much larger than a snippet.

Query syntax:

  • AND/OR/NOT: NFProfile AND heartbeat

  • Phrase: "nf instances"

  • Prefix: subscri*

  • Column filter: name:NFProfile or body:nfInstanceId or api_name:Nnrf_NFManagement

  • Hyphenated, dotted or underscored terms (e.g. nf-instances, 29.510, Nnrf_NFManagement) are auto-quoted to avoid FTS5 syntax errors.

Tokenization:

  • Unlike search, this index applies no stemming: identifiers are matched as written, and inflected English forms do not fold together.

  • '-', '.' and '_' split tokens, so Nnrf_NFManagement is indexed as "nnrf" and "nfmanagement" and /nf-instances as "nf" and "instances" — a partial name matches, but camelCase is not split (supportedFeatures is one token).

Pagination:

  • Results come as {results, total_count, limit, offset}; total_count is the full match count.

  • Use limit (default 10, max 200) and offset to page through matches beyond the first page.

Inputs: query (required), kind, limit, offset, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Every tool targets a distinct content type or operation: listing vs. retrieval, specification text vs. ASN.1 vs. OpenAPI vs. images vs. cross-references. The two search tools explicitly separate specification clauses from OpenAPI definitions, eliminating ambiguity.

    Naming Consistency5/5

    All tools use a consistent lowercase snake_case convention with a verb-noun pattern (list_*, get_*, search_*, compare_versions). No mixed conventions or irregular names, making it easy to infer functionality from the name.

    Tool Count5/5

    13 tools is a well-scoped set for a specification retrieval system. Each tool adds a distinct capability—discovery, reading, searching, comparison, images, ASN.1, OpenAPI, references—without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full lifecycle of read-only specification access: discovery (list_specs, list_versions, list_openapi, list_images), retrieval (get_section, get_image, get_asn1, get_openapi), searching (search, search_openapi), comparison (compare_versions), and cross-references (get_references). No obvious gaps for the stated domain.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to access and search 3GPP telecommunications specifications through direct integration with the TSpec-LLM dataset. Provides real-time specification content, implementation requirements, and multi-spec comparisons for 3GPP standards development.
      4
      29
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      D
      maintenance
      Generic MCP server that exposes Markdown documentation to LLMs, enabling them to search and answer questions about any software documentation.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that indexes documents and serves relevant context to LLMs via Retrieval Augmented Generation (RAG).
      35 npm
      36
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A local-first MCP server that ingests PDFs, extracts structure, and provides semantic search and sequential navigation tools for AI clients to query and learn from documents.
      10
      MIT