🔌 MCP Server Toolkit

Build plug-and-play MCP servers for any dev workflow — code search, docs, databases, and more.

![npm version](https://www.npmjs.com/package/mcp-server-toolkit) ![MCP](https://glama.ai/mcp/servers/naveenayalla1-CS50/mcp-server-toolkit) ![License: MIT](LICENSE) ![TypeScript](https://www.typescriptlang.org/) ![Works with Claude Code](https://docs.anthropic.com/claude-code) ![Works with Cursor](https://cursor.sh) ![Works with Windsurf](https://codeium.com/windsurf) ![PRs Welcome](CONTRIBUTING.md) ![Stars](https://github.com/naveenayalla1-CS50/mcp-server-toolkit/stargazers)

Give any AI coding agent a direct line into your codebase, docs, or database — in under 60 seconds.

Quick Start · Servers · Build Your Own · Discord · Changelog

---

!Demo: Claude Code querying a codebase via MCP Server Toolkit

</div>

---

Why this exists

When you ask Claude Code "where do we handle Stripe webhooks?" it has two bad options:

Option A — Read every file in the repo. Slow, expensive, blows the context window on any real codebase.
Option B — Guess based on the first few files it sees. Wrong half the time.

MCP Server Toolkit gives agents a third option: ask the right tool directly. Semantic code search, live database queries, doc lookups, API introspection — all surfaced through the Model Context Protocol standard, so any MCP-compatible client can use them without any changes to your existing code.

---

✨ Features

🔍 Semantic code search — Find the right function, file, or pattern across your entire repo in milliseconds. Powered by vector embeddings, no Elasticsearch required.
📚 Docs server — Give your agent instant access to any documentation site, local Markdown files, or Notion workspace.
🗄️ Database server — Natural language → SQL for PostgreSQL, MySQL, and SQLite. Read-only by default, writable with an explicit flag.
🌐 API introspection server — Load any OpenAPI/Swagger spec and let your agent browse and call endpoints with type safety.
⚡ One-command setup — Every server ships as a standalone CLI. npx and pip install paths included.
🔒 Zero-config secrets — Reads from your existing .env file or environment variables. Nothing new to learn.
🧩 Works everywhere — Claude Code, Cursor, Windsurf, Cline, VS Code Copilot, Codex CLI, Gemini CLI, and every other MCP-compatible client.
🛠️ Extensible — The createServer() helper reduces a new tool to ~15 lines of TypeScript. Scaffold a custom server in 30 seconds.

---

🚀 Quick Start

Requirements: Node.js 18+ or Python 3.10+

Option A — npx (no install)

npx mcp-server-toolkit@latest init

This runs the interactive setup wizard. Pick your servers, paste your credentials, and get a ready-to-paste config block for Claude Code / Cursor.

---

Option B — npm global install

npm install -g mcp-server-toolkit
mcp init

---

Option C — pip (Python environments)

pip install mcp-server-toolkit
mcp init

---

Add to Claude Code

After mcp init, copy the generated block into your .claude/mcp.json:

{
  "servers": {
    "code-search": {
      "command": "mcp-code-search",
      "args": ["--root", "."],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }
    },
    "database": {
      "command": "mcp-database",
      "args": ["--read-only"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "docs": {
      "command": "mcp-docs",
      "args": ["--source", "./docs"]
    }
  }
}

That's it. Restart Claude Code and your agent now has full access to all three.

---

📦 Included Servers

| Server | Install | What it does | |--------|---------|-------------| | mcp-code-search | npx mcp-code-search | Semantic + keyword search across your codebase | | mcp-database | npx mcp-database | Natural language queries for Postgres, MySQL, SQLite | | mcp-docs | npx mcp-docs | Index and query local Markdown, Notion, or any URL | | mcp-openapi | npx mcp-openapi | Browse and call endpoints from any OpenAPI spec | | mcp-git | npx mcp-git | Query commits, diffs, blame, and branches | | mcp-shell | npx mcp-shell | Sandboxed shell execution with allowlist controls |

All servers are independently installable — use one or all of them.

---

🛠️ Usage Example

Once installed, your AI agent can use natural language to interact with your entire dev environment:

You:  "Find all places where we validate user input before inserting into the DB"

Agent uses mcp-code-search →
  Found 7 matches in: auth/validators.ts, api/users.ts, api/orders.ts...

You:  "How many users signed up in the last 7 days?"

Agent uses mcp-database →
  SELECT count(*) FROM users WHERE created_at > now() - interval '7 days';
  → 1,432 new users

You:  "What does our docs say about rate limiting?"

Agent uses mcp-docs →
  Found in docs/api/rate-limits.md: "All endpoints are limited to 100 req/min per API key..."

No copy-pasting. No context switching. The agent just knows.

---

🔧 Build Your Own Server

Scaffold a new server in 30 seconds:

mcp new my-server --template typescript

This generates:

my-server/
├── src/
│   ├── index.ts        # Entry point — register your tools here
│   └── tools/
│       └── example.ts  # Your first tool
├── package.json
└── README.md

A minimal tool looks like this:

import { createServer, tool, z } from 'mcp-server-toolkit';

const server = createServer({ name: 'my-server', version: '1.0.0' });

server.addTool(
  tool({
    name: 'get_weather',
    description: 'Get current weather for a city',
    input: z.object({ city: z.string() }),
    run: async ({ city }) => {
      const data = await fetchWeather(city);
      return { content: `${city}: ${data.temp}°C, ${data.condition}` };
    },
  })
);

server.start();

That's the whole thing. Ship it.

---

📁 Project Structure

mcp-server-toolkit/
├── packages/
│   ├── core/           # createServer(), tool(), z helpers
│   ├── code-search/    # Semantic codebase search server
│   ├── database/       # Natural language DB query server
│   ├── docs/           # Documentation indexing server
│   ├── openapi/        # OpenAPI spec introspection server
│   ├── git/            # Git history and diff server
│   └── shell/          # Sandboxed shell server
├── examples/
│   ├── claude-code/    # Drop-in config for Claude Code
│   ├── cursor/         # Drop-in config for Cursor
│   └── custom-server/  # Starter template for custom tools
├── docs/               # Full documentation
└── CONTRIBUTING.md

---

🗺️ Roadmap

[x] Code search (semantic + keyword)
[x] PostgreSQL / MySQL / SQLite server
[x] Docs server (Markdown + URL crawl)
[x] OpenAPI introspection server
[ ] Notion server
[ ] Linear / Jira server
[ ] Supabase + PlanetScale managed DB support
[ ] Web UI for browsing registered tools
[ ] Auto-generated tool descriptions from schema

Want something on this list prioritised? Open an issue and add a 👍.

---

🤝 Contributing

Contributions are what make this project worth starring. Here's how to get involved:

First time?

Look for issues labelled good first issue — these are scoped small on purpose.
Comment on the issue to claim it before starting.
Fork the repo, make your changes, open a PR.

Adding a new server

The fastest path to a merged PR:

# Clone and install deps
git clone https://github.com/naveenayalla1-CS50/mcp-server-toolkit
cd mcp-server-toolkit
npm install

# Scaffold your server
npm run new-server -- --name my-awesome-server

# Run tests
npm test

# Submit your PR

Each new server needs:

A README.md explaining what it does and the one-line install command
At least one test in __tests__/
An example config block for Claude Code / Cursor

Guidelines

Keep each tool focused on doing one thing well — resist scope creep.
Never store credentials in code — always read from env vars.
Add your server to the table in the main README and to the packages/ list.

Code of Conduct

Be excellent to each other. See CODE_OF_CONDUCT.md.

---

🔐 Security

All servers are read-only by default. Write access requires an explicit --writable flag.
Credentials are read from environment variables only — never hardcoded or logged.
The shell server uses an allowlist (mcp-shell.config.json) — no arbitrary command execution.
Found a vulnerability? Please email security@naveenayalla1-CS50.dev instead of opening a public issue.

---

📄 License

You're free to use this in personal projects, commercial products, and anything in between. Attribution appreciated but not required.

---

Share on Twitter · Open an issue

Built with ❤️ for the agent era.

</div>

MCP server usage

This repository contains a TypeScript/Node.js toolkit of MCP servers.

Install

npm install
npm run build
npm run build --workspace=@mcp-toolkit/core
npm run build --workspace=@mcp-toolkit/code-search
node packages/code-search/dist/index.js



## MCP server usage

This repository contains a TypeScript/Node.js toolkit of MCP servers.

### Install

npm install npm run build

mcp-server-toolkit