How do I use mcp-server-3gpp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-3gpp Explain 5GMM cause 27 from TS 24.501" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-server-3gpp

🔍 MCP Server for 3GPP Specification Document Search

A Model Context Protocol (MCP) server that enables AI assistants to search and retrieve information from 3GPP specification documents.

Features

📚 Search 3GPP Documents: Full-text search across 3GPP specifications
📋 EMM/5GMM Cause Lookup: Quick reference for LTE and 5G NAS cause values
🎯 Pre-built Data Included: Ready to use immediately after installation
🔄 MCP SDK v1.0.0 Compatible: Full support for structured responses
✅ Comprehensive Testing: 13 test scenarios with validation tools

✅ Included Specifications (Pre-processed)

TS 24.008 - 2G/3G NAS (MM/GMM/SM/CC)
TS 24.301 - LTE NAS (EMM/ESM)
TS 24.501 - 5G NAS (5GMM/5GSM)
TS 36.300 - E-UTRA Overall Description

📥 Additional Specifications (User can add)

The MCP server architecture supports expanding to more specifications. Users can add:

PCT (Protocol Conformance Test)

TS 51.010-1 (2G), TS 34.123-1 (3G), TS 36.523-1 (4G), TS 38.523-1 (5G)

Protocol

TS 31.121 (USIM), TS 31.124 (USAT)

IMS

TS 34.229-1 (4G IMS), TS 34.229-5 (5G IMS)

Architecture

TS 38.300 (NR Overall), TR 37.901 (Data Throughput)

RF (if needed)

TS 36.521, TS 38.521 series, etc.

To add specifications: Download PDFs → Run npm run setup

Available Tools

Tool	Description
`search_3gpp_docs`	Search 3GPP documents by keywords
`get_emm_cause`	Get EMM cause (LTE) or 5GMM cause (5G) details
`list_specs`	List available specifications

Testing & Validation

This package includes comprehensive testing tools:

# Run all SpecKit user story tests (13 scenarios) npm test # Validate data structure and MCP server npm run validate

Test Coverage:

✅ 13 acceptance scenarios from SpecKit specs
✅ All 3 MCP tools (search, get_emm_cause, list_specs)
✅ Data structure validation (22,408 chunks)
✅ EMM/5GMM cause lookup verification

Installation

Prerequisites

Node.js >= 18.0.0
Git LFS (for downloading pre-built data)

Quick Start (Recommended)

# Install Git LFS (if not already installed) git lfs install # Clone and install git clone https://github.com/Lee-SiHyeon/mcp-server-3gpp.git cd mcp-server-3gpp npm install # If chunks.json is a pointer file, pull LFS data git lfs pull # ✅ Ready to use! Pre-built data with 17 specs included. npm start

Note: The pre-built chunks.json (107MB) is stored with Git LFS. If you don't have Git LFS installed, you can still use the MCP server for EMM/5GMM cause lookup, or generate data yourself using the scripts.

Included Specs

The package includes pre-processed chunks for 17 specifications:

NAS Layer (4 specs)

TS 24.008 (2G/3G NAS)
TS 24.301 (LTE NAS)
TS 24.501 (5G NAS)
TS 36.300 (E-UTRA Architecture)

RRC - Radio Resource Control (3 specs) 🆕

TS 25.331 (3G UMTS RRC - SIB details)
TS 36.331 (4G LTE RRC - SIB details)
TS 38.331 (5G NR RRC - SIB details)

PCT - Protocol Conformance Test (4 specs)

TS 51.010-1 (2G Protocol)
TS 34.123-1 (3G Protocol)
TS 36.523-1 (4G Protocol)
TS 38.523-1 (5G Protocol)

USIM/USAT (2 specs)

TS 31.121 (USIM)
TS 31.124 (USAT)

IMS (2 specs)

TS 34.229-1 (4G IMS)
TS 34.229-5 (5G IMS)

Architecture (2 specs)

TS 38.300 (5G NR)
TR 37.901 (Data Throughput)

Total: 22,408 pre-built chunks, ~107MB

Optional: Update Data

If you want to regenerate data with the latest 3GPP specifications:

# Option 1: Automatic (downloads and processes PDFs) npm run setup # Option 2: Manual # Step 1: Download PDFs npm run download-pdfs # Step 2: Extract and chunk npm run prepare-data

Data Preparation

✅ Pre-built Data Included (Git LFS)

This package includes pre-processed 3GPP specification data (chunks.json) with 17 specifications and 22,408 chunks (~107MB).

Important: The data file is stored using Git LFS (Large File Storage).

If you have Git LFS installed:

git lfs pull # Download the actual data file

If you don't have Git LFS:

# Option 1: Install Git LFS (recommended) # Windows: Download from https://git-lfs.github.com/ # Mac: brew install git-lfs # Linux: sudo apt-get install git-lfs git lfs install git lfs pull # Option 2: Manual download # Download chunks.json from GitHub releases or generate it yourself (see below)

Without Git LFS: The MCP server will still work for EMM/5GMM cause lookup. Full document search requires the data file.

📥 Add More Specifications (Optional)

Want to add more specifications? Follow these steps:

Prerequisites

# Install Python dependencies (required for PDF processing) pip install pymupdf

Option 1: Automatic Download

Download additional specifications automatically:

# Download PCT specs (Protocol, USIM, USAT, IMS, Architecture) python scripts/download_pct_specs.py # Download RRC specs (3G/4G/5G RRC with SIB details) 🆕 python scripts/download_rrc_specs.py

PCT specs include:

Protocol: TS 51.010-1 (2G), TS 34.123-1 (3G), TS 36.523-1 (4G), TS 38.523-1 (5G)
USIM/USAT: TS 31.121, TS 31.124
IMS: TS 34.229-1, TS 34.229-5
Architecture: TS 38.300, TR 37.901

RRC specs include (for SIB details):

TS 25.331 (3G UMTS RRC)
TS 36.331 (4G LTE RRC)
TS 38.331 (5G NR RRC)

Option 2: Manual Download

Download specifications manually from:

Place PDFs in the raw/ folder.

Process PDFs and Update chunks.json

After downloading PDFs:

# Step 1: Extract text from all PDFs in raw/ folder python scripts/extract_pdf.py # Step 2: Create chunks from extracted text python scripts/create_chunks_simple.py # Step 3: Copy to data folder # Windows: copy "extracted\chunks.json" "data\chunks.json" # Linux/Mac: cp extracted/chunks.json data/chunks.json

Advanced: Customize Scripts

All scripts are fully editable:

scripts/download_pct_specs.py - Modify to download different specs
scripts/extract_pdf.py - Adjust text extraction settings
scripts/create_chunks_simple.py - Change chunk size/overlap

Example: Edit download_pct_specs.py to add new specifications:

SPECS = [ { 'name': 'ts_your_spec', 'series': '12300_12399', # ETSI series folder 'spec_num': '123001', # Spec number 'version': '18.00.00_60', # Target version 'description': 'Your Spec Description' }, # Add more specs... ]

Configuration

VS Code / GitHub Copilot

Add to your workspace .vscode/mcp.json:

{ "servers": { "3gpp-docs": { "type": "stdio", "command": "node", "args": ["/path/to/mcp-server-3gpp/src/index.js"] } } }

Claude Desktop

Add to your claude_desktop_config.json:

{ "mcpServers": { "3gpp-docs": { "command": "node", "args": ["/path/to/mcp-server-3gpp/src/index.js"] } } }

Custom Data Path

Set the CHUNKS_FILE_PATH environment variable to use a custom chunks file location:

{ "servers": { "3gpp-docs": { "type": "stdio", "command": "node", "args": ["/path/to/mcp-server-3gpp/src/index.js"], "env": { "CHUNKS_FILE_PATH": "/path/to/your/chunks.json" } } } }

Usage Examples

Once configured, you can ask your AI assistant:

"What is EMM cause #3?"
"Search for attach procedure in 3GPP docs"
"Explain 5GMM cause #7"
"Find information about tracking area update"
"List all available 3GPP specifications"
"Search for SIB information in RRC specs"

Response Format

All tools return structured responses compatible with MCP SDK v1.0.0:

{ "content": [ { "type": "text", "text": "Human-readable response" } ], "structuredContent": { "results": [ { "source": "ts_124301_v18.9.0_LTE_NAS", "content": "Detailed specification text..." } ] } }

This allows AI clients to:

Display formatted text to users
Process structured data programmatically
Integrate with automation workflows

EMM/5GMM Cause Quick Reference

Common EMM Causes (LTE - TS 24.301)

Cause	Name
#3	Illegal UE
#6	Illegal ME
#7	EPS services not allowed
#11	PLMN not allowed
#12	Tracking Area not allowed
#15	No Suitable Cells In TA
#22	Congestion

Common 5GMM Causes (5G - TS 24.501)

Cause	Name
#3	Illegal UE
#6	Illegal ME
#7	5GS services not allowed
#11	PLMN not allowed
#62	No network slices available
#65	Maximum PDU sessions reached

Project Structure

mcp-server-3gpp/ ├── src/ │ └── index.js # MCP server implementation ├── scripts/ │ ├── extract_pdf.py # PDF text extraction (editable) │ ├── create_chunks_simple.py # Text chunking (editable) │ ├── download_pct_specs.py # Auto-download PCT specs (editable) │ ├── download_rrc_specs.py # Auto-download RRC specs (editable) 🆕 │ ├── download-pdfs.js # Download NAS specs │ └── postinstall.js # Post-install setup ├── data/ │ └── chunks.json # Pre-built chunks (22,408 chunks, 107MB) ├── test_speckit_userstories.js # Comprehensive test suite 🆕 ├── validate.js # Data & server validation 🆕 ├── raw/ # Place PDFs here (optional) ├── extracted/ # Extracted text files (generated) ├── package.json └── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file.

Disclaimer

This project is not affiliated with 3GPP. 3GPP specifications are copyrighted by ETSI and 3GPP partners. Users are responsible for complying with 3GPP's terms of use when downloading and using specification documents.

Developer Documentation

SpecKit (Spec-Driven Development)

This project uses SpecKit for maintaining development context and collaboration.

What is SpecKit?

SpecKit is a Spec-Driven Development framework that helps developers and AI agents maintain shared context through structured specifications.

Key Principle: Specifications come first, code follows.

SpecKit Workflow

Constitution → Specify → Plan → Tasks → Implement

Constitution (.specify/constitution.md): Project principles, technical stack, historical decisions
Specs (.specify/specs/): Feature specifications with user stories and acceptance criteria
Plans (.specify/plans/): Technical implementation plans and architecture
Tasks (.specify/tasks/): Granular task breakdowns with dependencies

Using SpecKit

If you have Claude Desktop or VS Code with the SpecKit extension:

Available Slash Commands:

/speckit-constitution - View/update project constitution
/speckit-specify - Create feature specifications
/speckit-plan - Create implementation plans
/speckit-tasks - Break down tasks
/speckit-implement - Execute implementation
/speckit-clarify - Clarify ambiguous specifications
/speckit-analyze - Analyze consistency across specs
/speckit-checklist - Quality checklist
/speckit-taskstoissues - Convert tasks to GitHub Issues

Manual Access: All SpecKit files are in .specify/ directory and can be read/edited directly:

.specify/ ├── constitution.md # Project overview ├── specs/ │ └── 001-3gpp-document-search.md ├── plans/ │ └── 001-implementation-plan.md ├── tasks/ │ └── 001-tasks.md └── templates/ # Templates for new features

Why SpecKit for this Project?

Context Sharing: NAD team and future developers have complete project history
AI Collaboration: AI agents understand design decisions and constraints
Onboarding: New contributors can read specs instead of reverse-engineering code
Documentation: Living documentation that evolves with code

mcp-server-3gpp

Features

✅ Included Specifications (Pre-processed)

📥 Additional Specifications (User can add)

Available Tools

Testing & Validation

Installation

Prerequisites

Quick Start (Recommended)

Included Specs

Optional: Update Data

Data Preparation

✅ Pre-built Data Included (Git LFS)

If you have Git LFS installed:

If you don't have Git LFS:

📥 Add More Specifications (Optional)

Prerequisites

Option 1: Automatic Download

Option 2: Manual Download

Process PDFs and Update chunks.json

Advanced: Customize Scripts

Configuration

VS Code / GitHub Copilot

Claude Desktop

Custom Data Path

Usage Examples

Response Format

EMM/5GMM Cause Quick Reference

Common EMM Causes (LTE - TS 24.301)

Common 5GMM Causes (5G - TS 24.501)

Project Structure

Contributing

License

Disclaimer

Developer Documentation

SpecKit (Spec-Driven Development)

What is SpecKit?

SpecKit Workflow

Using SpecKit

Why SpecKit for this Project?

Related Projects

Resources

New MCP Servers

Latest Blog Posts

MCP directory API