# 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)
```bash
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
```bash
claude mcp add --transport stdio openzeppelin-docs -- npx -y openzeppelin-docs-mcp
```
### Verify Installation
```bash
# List configured servers
claude mcp list
# Check server status (inside Claude Code)
/mcp
```
## Building from Source
If you want to build and run locally:
```bash
# 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
```bash
claude mcp add --transport stdio openzeppelin-docs -- node /absolute/path/to/openzeppelin-docs-mcp/dist/index.js
```
Or manually add to `~/.claude.json`:
```json
{
"mcpServers": {
"openzeppelin-docs": {
"command": "node",
"args": ["/absolute/path/to/openzeppelin-docs-mcp/dist/index.js"]
}
}
}
```
### Testing with MCP Inspector
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
## Available Tools
### `search_oz_docs`
Search OpenZeppelin Contracts documentation for guides, API references, and code examples.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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
```bash
# 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](https://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
