# solidit-mcp-server

[![npm version](https://img.shields.io/npm/v/solidit-mcp-server)](https://www.npmjs.com/package/solidit-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

Give AI assistants instant access to Solodit's 49,000+ blockchain vulnerability database.

An [MCP](https://modelcontextprotocol.io/) server that connects Claude (and other MCP clients) to the [Solodit](https://solodit.cyfrin.io/) audit findings API -- search vulnerabilities, browse recent discoveries, and look up specific findings directly from your AI workflow.

Runs via `npx solidit-mcp-server` with zero global installation required.

## Quick Start

1. **Get an API key** at [solodit.cyfrin.io](https://solodit.cyfrin.io/) (Profile > API Keys)

2. **Add the MCP config** (see [Claude Code](#claude-code) or [Claude Desktop](#claude-desktop) below)

3. **Start using it** -- ask Claude something like:
   > "Search for reentrancy vulnerabilities in DeFi protocols"

## Claude Code

Add to your `.mcp.json` (project-level) or `~/.claude/mcp.json` (global):

```json
{
  "mcpServers": {
    "solodit": {
      "command": "npx",
      "args": ["-y", "solidit-mcp-server"],
      "env": { "SOLODIT_API_KEY": "your-api-key-here" }
    }
  }
}
```

## Claude Desktop

Add to your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "solodit": {
      "command": "npx",
      "args": ["-y", "solidit-mcp-server"],
      "env": { "SOLODIT_API_KEY": "your-api-key-here" }
    }
  }
}
```

## Docker

Build and run locally:

```bash
docker build -t solidit-mcp-server .
docker run -i -e SOLODIT_API_KEY=your-api-key-here solidit-mcp-server
```

Or use docker-compose with a `.env` file:

```bash
# .env
SOLODIT_API_KEY=your-api-key-here
```

```bash
docker compose up
```

## Tools

### `search_findings`

Full-featured search across Solodit's database with 14+ filters. All parameters are optional -- a bare call returns recent findings.

| Parameter | Type | Description |
|-----------|------|-------------|
| `keywords` | string | Free-text search across titles and content |
| `impact` | string[] | Severity filter: `HIGH`, `MEDIUM`, `LOW`, `GAS` |
| `tags` | string[] | Vulnerability type: `Reentrancy`, `Oracle`, `Access Control`, `Integer Overflow/Underflow`, `Front-running`, `Logic Error`, `DOS`, `Price Manipulation`, `Flash Loan`, `Griefing`, etc. |
| `firms` | string[] | Audit firm: `Cyfrin`, `Sherlock`, `Code4rena`, `Trail of Bits`, `OpenZeppelin`, etc. |
| `protocol_category` | string[] | Protocol type: `DeFi`, `NFT`, `Lending`, `DEX`, `Staking`, `Governance`, `Bridge`, etc. |
| `language` | string[] | Language: `Solidity`, `Rust`, `Cairo`, `Vyper`, `Move` |
| `protocol` | string | Protocol name (partial match) |
| `finder` | string | Auditor handle (partial match) |
| `quality_min` | number | Minimum quality score (0-5) |
| `rarity_min` | number | Minimum rarity score (0-5) |
| `date_range` | string | Preset: `30`, `60`, `90` days, or `alltime` |
| `date_after` | string | Custom date cutoff (ISO format, e.g. `2024-01-01`) |
| `sort_by` | string | `Recency`, `Quality`, or `Rarity` |
| `sort_direction` | string | `Desc` or `Asc` |
| `page` | number | Page number (default: 1) |
| `page_size` | number | Results per page (default: 20, max: 100) |
| `max_content_length` | number | Content preview length (default: 500, max: 5000) |

**Example:** "Find high-impact reentrancy findings in DeFi protocols audited by Cyfrin"

### `get_finding_detail`

Retrieve the full content and metadata of a single finding by ID or slug. Use after seeing a result in `search_findings` to get the complete writeup.

| Parameter | Type | Description |
|-----------|------|-------------|
| `finding_id` | string | The finding ID (UUID) or slug from search results or Solodit URLs |

**Example:** "Get the full details of finding abc-123-def"

### `search_by_tag`

Search by vulnerability tags, sorted by quality score (best examples first). Ideal for finding high-quality writeups about a specific vulnerability class.

| Parameter | Type | Description |
|-----------|------|-------------|
| `tags` | string[] | **Required.** One or more vulnerability tags |
| `impact` | string[] | Severity filter: `HIGH`, `MEDIUM`, `LOW`, `GAS` |
| `language` | string[] | Language filter |
| `protocol_category` | string[] | Protocol category filter |
| `page` | number | Page number (default: 1) |
| `page_size` | number | Results per page (default: 10, max: 100) |

**Example:** "Find the best oracle manipulation examples in Solidity"

### `recent_findings`

Browse the latest findings from the last N days, sorted by recency (newest first).

| Parameter | Type | Description |
|-----------|------|-------------|
| `days` | number | Days to look back (default: 30) |
| `impact` | string[] | Severity filter: `HIGH`, `MEDIUM`, `LOW`, `GAS` |
| `language` | string[] | Language filter |
| `protocol_category` | string[] | Protocol category filter |
| `page` | number | Page number (default: 1) |
| `page_size` | number | Results per page (default: 10, max: 100) |

**Example:** "Show me high-impact findings from the last 7 days"

## API Key

This server requires a Solodit API key. Get yours at [solodit.cyfrin.io](https://solodit.cyfrin.io/) under Profile > API Keys.

The key is passed via the `SOLODIT_API_KEY` environment variable in your MCP configuration (see setup sections above).

## License

[MIT](./LICENSE)