OpenZeppelin Docs MCP Server

An MCP (Model Context Protocol) server that provides offline search and retrieval of OpenZeppelin Contracts documentation. Pre-indexes documentation at build time using SQLite with FTS5 for fast full-text search.

Features

• Offline capable - Works without internet after initial setup
• Fast lookups - Pre-built SQLite index with FTS5 full-text search
• Contract-aware - Understands Solidity structure (functions, events, modifiers, errors)
• Version aware - Supports OpenZeppelin Contracts v4.x and v5.x
• NatSpec extraction - Parses documentation directly from Solidity source files

Installation

Quick Install (GitHub)

claude mcp add --transport stdio openzeppelin-docs -- npx -y github:pbuda/openzeppelin-docs-mcp

The index will be built automatically on first run (~2-3 minutes).

Install from npm

claude mcp add --transport stdio openzeppelin-docs -- npx -y openzeppelin-docs-mcp

Verify Installation

# List configured servers
claude mcp list

# Check server status (inside Claude Code)
/mcp

Building from Source

If you want to build and run locally:

# Clone the repository
git clone https://github.com/pbuda/openzeppelin-docs-mcp.git
cd openzeppelin-docs-mcp

# Install dependencies
npm install

# Build the documentation index (fetches repos, ~2-3 min)
npm run build:index

# Build TypeScript
npm run build

Add Local Build to Claude Code

claude mcp add --transport stdio openzeppelin-docs -- node /absolute/path/to/openzeppelin-docs-mcp/dist/index.js

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "openzeppelin-docs": {
      "command": "node",
      "args": ["/absolute/path/to/openzeppelin-docs-mcp/dist/index.js"]
    }
  }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Available Tools

search_oz_docs

Search OpenZeppelin Contracts documentation for guides, API references, and code examples.

{
  "query": "reentrancy guard",
  "version": "5.x",
  "category": "all",
  "limit": 5
}

Parameters:

• query (required) - Search query (e.g., "ERC20 approve", "access control roles")
• version - "4.x", "5.x", or "all" (default: "5.x")
• category - "access", "token", "utils", "governance", "proxy", "finance", "metatx", or "all"
• limit - Max results (default: 5)

get_oz_contract

Get detailed API reference for a specific contract or library.

{
  "name": "ERC20",
  "version": "5.x"
}

Parameters:

• name (required) - Contract or library name (e.g., "Ownable", "ECDSA", "SafeERC20")
• version - "4.x" or "5.x" (default: "5.x")

Returns: Contract metadata, inheritance chain, all functions/events/errors with signatures and NatSpec.

get_oz_function

Get detailed information about a specific function.

{
  "function_name": "ECDSA.recover",
  "version": "5.x"
}

Parameters:

• function_name (required) - Function name, optionally with contract (e.g., "transfer", "ERC20.transferFrom")
• version - "4.x" or "5.x" (default: "5.x")

Returns: Function signature, parameters with types and descriptions, return values, NatSpec documentation.

list_oz_modules

List all available contracts and libraries, optionally filtered by category.

{
  "category": "utils",
  "version": "5.x"
}

Parameters:

• category - Filter by category or "all" (default: "all")
• version - "4.x" or "5.x" (default: "5.x")

Returns: Organized list of all contracts/libraries grouped by category.

Development

# Run in development mode (with hot reload)
npm run dev

# Rebuild the index (skip fetching if repos exist)
npx tsx scripts/build-index.ts --skip-fetch

# Force re-clone repositories
npx tsx scripts/build-index.ts --force

Data Sources

The indexer fetches and parses:

1. OpenZeppelin Docs - MDX documentation from github.com/OpenZeppelin/docs
2. OpenZeppelin Contracts v5.3.0 - Solidity source with NatSpec comments
3. OpenZeppelin Contracts v4.9.6 - Solidity source with NatSpec comments

Database Statistics

After indexing:

• ~927 documentation chunks from MDX files
• ~357 contracts (191 v5.x, 166 v4.x)
• ~3,067 members (functions, events, modifiers)

License

MIT