Merkl Server

An MCP server exposing Merkl Opportunities endpoints using @modelcontextprotocol/sdk.

Setup

• Node.js 18+ recommended
• Install deps

npm install

Optionally set environment variables:

• MERKL_BASE_URL (default: https://api.merkl.xyz)
• MERKL_API_KEY (Bearer token if you have one; public endpoints work without it)

Run (local)

• Dev server:

npm run dev

• Start once:

npm run build
npm start

• Smoke test (direct HTTP call, not MCP):

npm run smoke

Tools exposed

• opportunities-search
• opportunities-get
• opportunities-campaigns
• opportunities-count
• opportunities-bins-apr
• opportunities-bins-tvl
• opportunities-aggregate
• opportunities-aggregate-max
• opportunities-aggregate-min

Use with an MCP-compatible client

This server uses the stdio transport. Point your MCP client to run the command and read/write on stdio:

• Command:

npx merkl-mcp

• Or locally via repo:

npm start

Set env vars as needed (e.g. MERKL_API_KEY). The server will register tools listed above.

Note: Requires Node 18+. Enable debug logs by setting MERKL_DEBUG=1.

One-line npx startup

After publishing as merkl-mcp to npm (or using npm link), you can start the server with:

npx merkl-mcp

If dist/server.js is missing, the CLI will build automatically on first run.

Connect to Claude Desktop (macOS)

Claude Desktop supports MCP over stdio. Add this server to Claude's config and restart the app.

1. Create or edit config file

• Path: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Use the published package (one-line npx)

{
  "mcpServers": {
    "merkl": {
      "command": "npx",
      "args": ["-y", "merkl-mcp"],
      "env": {
        "MERKL_API_KEY": "(Optional) YOUR_API_KEY_OR_REMOVE_IF_UNUSED"
      }
    }
  }
}

1. Or run from local repo

{
  "mcpServers": {
    "merkl": {
      "command": "node",
      "args": ["dist/src/server.js"],
      "cwd": "./merkl-mcp",
      "env": {
        "MERKL_API_KEY": "(Optional) YOUR_API_KEY_OR_REMOVE_IF_UNUSED"
      }
    }
  }
}

1. Restart Claude Desktop

• Start a new chat; the tool named merkl should appear in the Tools list.

Troubleshooting

• Ensure Node.js 18+ is installed and available to Claude's environment.
• Remove MERKL_API_KEY if you don't have one; public endpoints work without it.
• Check Claude logs if tools don't appear; verify the config file path and JSON syntax.

Publish to npm

Set the name in package.json (already set up for you via bin aliases) and publish:

npm login   # if not already
npm publish --access public

Then users can run:

npx merkl-mcp
# or the short alias
npx merkl-mcp