# Midnight MCP Server
> ## ⚠️ Deprecated — use Kapa + Midnight Expert
>
> **midnight-mcp is being wound down.** Midnight has standardised on two official tools:
>
> - **Kapa MCP** (docs Q&A / search): `claude mcp add --transport http midnight https://midnight.mcp.kapa.ai`
> - **Midnight Expert** (hands-on dev, Claude Code plugins): `curl -fsSL https://midnightntwrk.expert/install.sh | bash`
>
> **Migration guide → https://docs.midnight.network/blog/migrating-to-kapa-and-midnight-expert**
[](https://www.npmjs.com/package/midnight-mcp)
[](https://npm-stat.com/charts.html?package=midnight-mcp)
[](./LICENSE)
[](https://www.typescriptlang.org/)
[](https://github.com/Olanetsoft/midnight-mcp/actions/workflows/ci.yml)
MCP server that gives AI assistants access to Midnight blockchain—search contracts, analyze code, and explore documentation.
This project extends the Midnight Network with additional developer tooling.
## Requirements
- **Node.js 20+** (LTS recommended)
Check your version: `node --version`
Using nvm? Click for Claude Desktop setup
If you use nvm, Claude Desktop may not see your nvm-managed Node. Use this config instead:
```json
{
"mcpServers": {
"midnight": {
"command": "/bin/sh",
"args": [
"-c",
"source ~/.nvm/nvm.sh && nvm use 20 >/dev/null 2>&1 && npx -y midnight-mcp@latest"
]
}
}
}
```
## Quick Start
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"midnight": {
"command": "npx",
"args": ["-y", "midnight-mcp@latest"]
}
}
}
```
**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
### Cursor
One-click install:
[](https://cursor.com/en-US/install-mcp?name=midnight&config=eyJjb21tYW5kIjoibnB4IC15IG1pZG5pZ2h0LW1jcEBsYXRlc3QifQ==)
Or manually add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"midnight": {
"command": "npx",
"args": ["-y", "midnight-mcp@latest"]
}
}
}
```
### VS Code Copilot
Add to `.vscode/mcp.json` or use Command Palette: `MCP: Add Server` → "command (stdio)" → `npx -y midnight-mcp@latest`
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"midnight": {
"command": "npx",
"args": ["-y", "midnight-mcp@latest"]
}
}
}
```
**No API keys required.** Restart your editor after adding the config.
> **Why `@latest`?** Unlike cached npx packages that never auto-update, `@latest` ensures you get new features and fixes on each restart. If upgrading from an older config without `@latest`, also clear your npx cache: `rm -rf ~/.npm/_npx`
---
## What's Included
### 29 Tools
| Category | Tools | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| **Search** | `search-compact`, `search-typescript`, `search-docs`, `fetch-docs` | Semantic search + live docs fetching |
| **Analysis** | `analyze-contract`, `explain-circuit`, `extract-contract-structure`, `compile-contract` | Static analysis + real compilation |
| **Repository** | `get-file`, `list-examples`, `get-latest-updates` | Access files and examples |
| **Versioning** | `get-version-info`, `check-breaking-changes`, `get-migration-guide`, `get-file-at-version`, `compare-syntax`, `get-latest-syntax` | Version tracking and migration |
| **AI Generation** | `generate-contract`, `review-contract`, `document-contract` | AI-powered code generation _(requires sampling)_ |
| **Compound** | `upgrade-check`, `get-repo-context` | Multi-step operations _(saves 50-70% tokens)_ |
| **Health** | `health-check`, `get-status`, `check-version` | Server status and version checking |
| **Discovery** | `list-tool-categories`, `list-category-tools`, `suggest-tool` | Explore available tools and get recommendations |
All tools are prefixed with `midnight-` (e.g., `midnight-search-compact`).
### Real Contract Compilation
The `midnight-compile-contract` tool validates Compact code using a hosted compiler service:
```
✅ Compilation successful (Compiler v0.29.0) in 2841ms
```
- **Fast mode** (`skipZk=true`): Syntax validation in ~1-2 seconds
- **Full mode** (`fullCompile=true`): Complete ZK circuit generation in ~10-30 seconds
- **Automatic fallback**: Falls back to static analysis if the compiler service is unavailable
This catches semantic errors that static analysis misses (sealed fields, disclose rules, type mismatches).
### MCP Capabilities
| Capability | Feature |
| --------------- | ----------------------------------------------- |
| **Tools** | 29 tools with `listChanged` notifications |
| **Resources** | 9 embedded resources with subscription support |
| **Prompts** | 5 workflow prompts |
| **Logging** | Client-controllable log level |
| **Completions** | Autocomplete for prompt arguments |
| **Progress** | Real-time progress for compound tools |
| **Sampling** | AI-powered generation (when client supports it) |
### 9 Embedded Resources
Quick references available offline:
- Compact syntax guide (v0.16-0.21)
- SDK API reference
- OpenZeppelin contracts
- Tokenomics overview
- Wallet integration
- Common errors & solutions
### Static Analysis
`extract-contract-structure` catches common mistakes before compilation:
| Check | Severity | Description |
| ------------------------- | -------- | ------------------------------------------------------- |
| `deprecated_ledger_block` | P0 | Catches `ledger { }` → use `export ledger field: Type;` |
| `invalid_void_type` | P0 | Catches `Void` → use `[]` (empty tuple) |
| `invalid_pragma_format` | P0 | Catches old pragma → use `>= 0.16 && <= 0.21` |
| `unexported_enum` | P1 | Enums need `export` for TypeScript access |
| `module_level_const` | P0 | Use `pure circuit` instead |
| + 10 more checks | P1-P2 | Overflow, division, assertions, etc. |
### 5 Prompts
- `create-contract` — Generate new contracts
- `review-contract` — Security and code review
- `explain-concept` — Learn Midnight concepts
- `compare-approaches` — Compare implementation patterns
- `debug-contract` — Troubleshoot issues
---
## Indexed Repositories
The API indexes **115+ Midnight repositories** from the entire Midnight ecosystem:
| Category | Count | Key Repositories |
| ------------------------ | ----- | -------------------------------------------------------------------------------- |
| **Compact Language** | 6 | `compact`, `compact-lsp`, `compact-tree-sitter`, `compact-zed` |
| **SDKs & APIs** | 5 | `midnight-js`, `midnight-sdk`, `midnight-wallet`, `midnight-dapp-connector` |
| **Core Infrastructure** | 9 | `midnight-node`, `midnight-indexer`, `midnight-ledger`, `midnight-zk` |
| **ZK & Cryptography** | 6 | `midnight-trusted-setup`, `fri`, `galois_recursion`, `pluto_eris` |
| **Documentation** | 5 | `midnight-docs`, `midnight-improvement-proposals`, `midnight-architecture` |
| **Examples & Templates** | 18 | `example-counter`, `example-bboard`, `example-kitties`, `example-zkloan` |
| **Identity** | 5 | `midnight-did`, `midnight-did-resolver`, `midnight-verifiable-credentials` |
| **Developer Tools** | 5 | `setup-compact-action`, `midnight-dev-utils`, `midnight-local-dev` |
| **Solutions & Apps** | 7 | `midnight-solutions`, `midnight-website-next`, `nightcap`, `ocp` |
| **Glacier Drop** | 15 | `midnight-glacier-drop-tools`, `gd-claim-api`, `gd-claim-portal` |
| **Partners & Community** | 20 | OpenZeppelin, BrickTowers, MeshJS, PaimaStudios, hackathon winners, Olanetsoft |
| **Other** | 18+ | Contracts, bridges, token distribution, monitoring, QA tools, community projects |
All **non-archived** repositories from the `midnightntwrk` organization plus community partners. See [api/README.md](api/README.md#indexed-repositories-115) for the complete list.
---
## Advanced Configuration
### HTTP Mode
Run as an HTTP server for web integrations or remote deployment:
```bash
# Start HTTP server on port 3000
npx midnight-mcp --http --port 3000
```
Endpoints:
- `/health` - Health check
- `/mcp` - Streamable HTTP (MCP protocol)
- `/sse` - Server-Sent Events
### CLI Options
```bash
npx midnight-mcp --help
Options:
--stdio Use stdio transport (default, for Claude Desktop)
--http Use HTTP transport with SSE support
--port HTTP port (default: 3000)
--json Output in JSON (default: YAML for better LLM efficiency)
--github-token GitHub token (overrides GITHUB_TOKEN env var)
-h, --help Show help
-v, --version Show version
```
> **Why YAML by default?** YAML is ~20-30% more token-efficient than JSON, which means AI assistants can process more context from tool responses.
### Local Mode
Run everything locally for privacy or offline use:
```json
{
"mcpServers": {
"midnight": {
"command": "npx",
"args": ["-y", "midnight-mcp@latest"],
"env": {
"MIDNIGHT_LOCAL": "true",
"OPENAI_API_KEY": "sk-...",
"CHROMA_URL": "http://localhost:8000"
}
}
}
}
```
Requires ChromaDB (`docker run -d -p 8000:8000 chromadb/chroma`) and OpenAI API key.
### GitHub Token
Add `"GITHUB_TOKEN": "ghp_..."` for higher GitHub API rate limits (60 → 5000 requests/hour).
---
## Developer Setup
```bash
git clone https://github.com/Olanetsoft/midnight-mcp.git && cd midnight-mcp
npm install && npm run build && npm test
# Lint & format
npm run lint # ESLint (typescript-eslint)
npm run lint:fix # Auto-fix lint issues
npm run format # Prettier
```
The hosted API runs on Cloudflare Workers + Vectorize. See [api/README.md](./api/README.md) for backend details.
---
## Links
- [Midnight Docs](https://docs.midnight.network)
- [MCP Spec](https://modelcontextprotocol.io)
- [Midnight GitHub](https://github.com/midnightntwrk)
## License
MIT
## Stargazers ⭐️
[](https://star-history.com/#Olanetsoft/midnight-mcp&Date)