Skip to content

zerotrust-labs/solodit-mcp

BranchesTags

Repository files navigation

Solodit MCP Server

A Model Context Protocol (MCP) server that provides access to Cyfrin Solodit, the world's largest database of smart contract security findings and vulnerabilities.

Features

  • Search 49,000+ Security Findings: Access comprehensive smart contract audit findings from major firms
  • Advanced Filtering: Filter by impact, audit firms, tags, protocols, languages, and more
  • Quality Metrics: Search by quality and rarity scores
  • Rate Limited API: Respects Solodit's rate limits (20 requests per 60 seconds)
  • Universal MCP Support: Works with Claude Desktop, Claude Code, Cursor, VS Code with GitHub Copilot, and any MCP-compatible client

Prerequisites

  • Node.js 18 or higher
  • A Solodit API key (get one from Cyfrin Solodit)

Installation

Recommended: Global Installation

Install the package globally to use it from anywhere:

# Clone or download this repository
cd solodit-mcp

# Install dependencies and build
npm install
npm run build

# Install globally (creates the 'solodit-mcp' command)
npm install -g .

After global installation, the solodit-mcp command will be available system-wide.

Alternative: Local Development

For development or if you prefer not to install globally:

cd solodit-mcp
npm install
npm run build

Then use the full path to dist/index.js in your configuration.

Configuration

1. Get Your API Key

Visit Cyfrin Solodit and obtain your API key.

2. Configure for Your MCP Client

Choose your preferred client below:

Claude Desktop

Edit the Claude Desktop config file:

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

If installed globally (recommended):

{
  "mcpServers": {
    "solodit": {
      "command": "solodit-mcp",
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

If using local installation:

{
  "mcpServers": {
    "solodit": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/solodit-mcp/dist/index.js"],
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

After saving, restart Claude Desktop.

Claude Code (CLI)

Claude Code automatically discovers MCP servers configured in your settings.

Create or edit ~/.config/claude-code/settings.json:

If installed globally (recommended):

{
  "mcpServers": {
    "solodit": {
      "command": "solodit-mcp",
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

If using local installation:

{
  "mcpServers": {
    "solodit": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/solodit-mcp/dist/index.js"],
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

Or use environment variables:

export SOLODIT_API_KEY=sk_your_api_key_here
claude-code
Cursor

Cursor supports MCP through its settings configuration.

Edit the Cursor config file:

macOS: ~/Library/Application Support/Cursor/User/settings.json Windows: %APPDATA%\Cursor\User\settings.json Linux: ~/.config/Cursor/User/settings.json

If installed globally (recommended):

{
  "mcpServers": {
    "solodit": {
      "command": "solodit-mcp",
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

If using local installation:

{
  "mcpServers": {
    "solodit": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/solodit-mcp/dist/index.js"],
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

Restart Cursor after making changes.

VS Code with GitHub Copilot

VS Code supports MCP servers through the GitHub Copilot extension (requires Copilot Chat).

Edit your VS Code settings:

macOS: ~/Library/Application Support/Code/User/settings.json Windows: %APPDATA%\Code\User\settings.json Linux: ~/.config/Code/User/settings.json

If installed globally (recommended):

{
  "github.copilot.chat.mcp.servers": {
    "solodit": {
      "command": "solodit-mcp",
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

If using local installation:

{
  "github.copilot.chat.mcp.servers": {
    "solodit": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/solodit-mcp/dist/index.js"],
      "env": {
        "SOLODIT_API_KEY": "sk_your_api_key_here"
      }
    }
  }
}

Alternatively, use the VS Code Command Palette:

  1. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
  2. Type "Preferences: Open User Settings (JSON)"
  3. Add the configuration above

Reload VS Code after configuration.

Note: MCP support in VS Code requires GitHub Copilot Chat extension v0.12.0 or later.

Other MCP Clients

For other MCP-compatible clients:

If installed globally:

{
  "command": "solodit-mcp",
  "env": {
    "SOLODIT_API_KEY": "sk_your_api_key_here"
  }
}

If using local installation:

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/solodit-mcp/dist/index.js"],
  "env": {
    "SOLODIT_API_KEY": "sk_your_api_key_here"
  }
}

Available Tools

1. search_findings

Search Solodit for smart contract security findings with advanced filtering options.

Parameters:

  • keywords (string): Search keywords to find in title and content
  • impact (array): Filter by severity - ["HIGH", "MEDIUM", "LOW", "GAS"]
  • firms (array): Filter by audit firm names (e.g., ["Cyfrin", "Sherlock", "Code4rena"])
  • tags (array): Filter by vulnerability tags (e.g., ["Reentrancy", "Oracle", "Access Control"])
  • protocol (string): Filter by protocol name (partial match)
  • protocolCategory (array): Filter by protocol categories (e.g., ["DeFi", "NFT", "Lending"])
  • languages (array): Filter by programming languages (e.g., ["Solidity", "Rust", "Cairo"])
  • user (string): Filter by finder/auditor handle (partial match)
  • minFinders (string): Minimum number of finders
  • maxFinders (string): Maximum number of finders
  • reportedDays (string): Time period - "30", "60", "90", or "alltime"
  • qualityScore (number): Minimum quality score (0-5)
  • rarityScore (number): Minimum rarity score (0-5)
  • sortField (string): Sort by "Recency", "Quality", or "Rarity"
  • sortDirection (string): "Desc" or "Asc"
  • page (number): Page number (default: 1)
  • pageSize (number): Results per page (default: 20, max: 100)

Example Usage:

Search for high severity reentrancy vulnerabilities:
- keywords: "reentrancy"
- impact: ["HIGH"]
- sortField: "Quality"
- pageSize: 10

2. get_finding_by_id

Get detailed information about a specific finding by its ID or slug.

Parameters:

  • keywords (string, required): The finding ID or slug to search for

Example Usage:

Get finding details by ID:
- keywords: "finding-id-12345"

Usage Examples

Example 1: Search for High Severity Findings

Use the search_findings tool with:
- impact: ["HIGH"]
- pageSize: 20
- sortField: "Recency"

Example 2: Find Oracle-Related Issues in DeFi

Use the search_findings tool with:
- tags: ["Oracle"]
- protocolCategory: ["DeFi"]
- qualityScore: 3

Example 3: Search Specific Audit Firm Reports

Use the search_findings tool with:
- firms: ["Cyfrin", "Trail of Bits"]
- impact: ["HIGH", "MEDIUM"]
- reportedDays: "30"

Example 4: Search by Keywords

Use the search_findings tool with:
- keywords: "flash loan attack"
- sortField: "Quality"
- sortDirection: "Desc"

Development

Run in Development Mode

npm run dev

Build

npm run build

Watch Mode

npm run watch

Rate Limiting

The Solodit API has a default rate limit of 20 requests per 60-second window. The server includes rate limit information in responses:

  • Total requests allowed
  • Remaining requests in current window
  • Time when the window resets

If you exceed the rate limit, you'll receive a 429 Too Many Requests error.

Error Handling

The server provides clear error messages for common issues:

  • Missing API Key: "SOLODIT_API_KEY environment variable is not set"
  • Invalid API Key: "Solodit API error (401): Invalid API key"
  • Rate Limit Exceeded: "Solodit API error (429): Rate limit exceeded"
  • Network Errors: Connection and timeout errors are properly reported

Available Filters Reference

Popular Audit Firms

  • Cyfrin
  • Sherlock
  • Code4rena
  • Trail of Bits
  • OpenZeppelin
  • Consensys Diligence
  • Pashov Audit Group
  • Spearbit
  • Hacken
  • Chainsecurity

Common Vulnerability Tags

  • Reentrancy
  • Oracle
  • Access Control
  • Integer Overflow/Underflow
  • Front-running
  • Logic Error
  • DOS
  • Price Manipulation
  • Flash Loan
  • Griefing

Protocol Categories

  • DeFi
  • NFT
  • Lending
  • DEX
  • Staking
  • Governance
  • Bridge
  • Options Vault
  • Yield Aggregator

Programming Languages

  • Solidity
  • Rust
  • Cairo
  • Vyper
  • Move

For a comprehensive list of all available filter values, see the Solodit API Documentation.

Project Structure

solodit-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── README.md
└── .env.example

Troubleshooting

API Key Issues

If you get authentication errors:

  1. Verify your API key is correct
  2. Ensure the environment variable is set properly
  3. Restart your MCP client after configuration changes

Connection Issues

If the server fails to connect:

  1. Check your internet connection
  2. Verify the Solodit API is accessible: curl https://solodit.cyfrin.io
  3. Check for any firewall or proxy issues

Server Not Showing Up

If the MCP server doesn't appear in your client:

  1. Verify the path to dist/index.js is absolute, not relative
  2. Check that the build completed successfully (npm run build)
  3. Ensure the config file JSON syntax is valid
  4. Restart your MCP client completely
  5. Check client logs for error messages

Rate Limit Issues

If you're hitting rate limits:

  1. Reduce the frequency of requests
  2. Implement delays between searches
  3. Use pagination wisely (larger page sizes for fewer requests)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Resources

Support

For issues related to:

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages