Solidity MCP Server

A Model Context Protocol server that turns Claude Code / Cline into a focused Solidity mentor by aggregating key Ethereum learning resources.

Prerequisites

• Node.js 18+
• npm 9+ (ships with Node 18)
• Internet access to fetch documentation sources on first run

1. Clone & Install

git clone <your-fork-or-repo-url> solidity-mcp
cd solidity-mcp
npm install

2. Configure Environment

Copy the sample environment file and adjust values when needed:

cp .env.example .env

Key settings:

• CACHE_DIR – where on-disk caches live (./data/cache by default)
• CACHE_TTL – cache lifetime in milliseconds (default 24h)
• MAX_CONCURRENT_REQUESTS / RATE_LIMIT_DELAY – tune scraper politeness

3. Build & Run

npm run build   # compile TypeScript to dist/
npm start       # launch the compiled MCP server

For rapid iteration you can use:

npm run dev     # runs src/index.ts via tsx with live reload

4. Optional: Smoke Test

npm run test    # exercises scrapers and service plumbing (requires network access)

5. Add to Cline MCPs

Update your Cline configuration (e.g. ~/.cline/config.json) with the new server:

{
  "mcp": {
    "servers": {
      "solidity-mcp": {
        "command": "node",
        "args": ["/absolute/path/to/solidity-mcp/dist/index.js"],
        "cwd": "/absolute/path/to/solidity-mcp",
        "env": {
          "CACHE_DIR": "/absolute/path/to/solidity-mcp/data/cache",
          "LOG_LEVEL": "info"
        }
      }
    }
  }
}

Be sure to replace /absolute/path/to/solidity-mcp with the actual location on your machine.

6. Usage Tips

• Use search_solidity_knowledge_base for hybrid results. The server now blends an indexed catalog with live scraper lookups, so even fuzzy queries tend to surface something useful.
• Combine get_solidity_code_examples and get_solidity_reference when explaining a new concept.
• Run get_source_overview to audit which collections are cached, see type breakdowns, and spot high-signal tags before diving deeper.
• Run refresh_content_cache if upstream docs have changed or results feel stale.

7. Updating

npm run build
npm start

After making code changes, rebuild and restart the MCP server before reconnecting from Cline.

---

Need help? Check solidity-mcp-setup.md for a more in-depth walkthrough.