AgentSkillsCN

mcp-setup

为 Claude 及其他 AI 代理搭建并集成 Model Context Protocol(MCP)服务器。当用户提出“搭建 MCP”“配置 MCP 服务器”“添加 MCP 工具”“连接 MCP”“创建 MCP 服务器”,或希望通过 MCP 协议集成外部工具时使用。

SKILL.md
--- frontmatter
name: mcp-setup
description: Model Context Protocol (MCP) server setup and integration for Claude and AI agents. Use when user asks to "setup MCP", "configure MCP server", "add MCP tools", "connect to MCP", "create MCP server", or integrate external tools via MCP protocol.

MCP Setup

Configure Model Context Protocol servers for Claude and AI agent integrations.

Claude Desktop Configuration

Config Location

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

Basic Configuration

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Popular MCP Servers

Filesystem

json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
  }
}

GitHub

json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
    }
  }
}

PostgreSQL

json
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
  }
}

SQLite

json
{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"]
  }
}

Brave Search

json
{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "your-api-key"
    }
  }
}

Slack

json
{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-xxxx",
      "SLACK_TEAM_ID": "T12345"
    }
  }
}

Custom MCP Server (Python)

Basic Structure

python
#!/usr/bin/env python3
from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("my-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="my_tool",
            description="Does something useful",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Input query"}
                },
                "required": ["query"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "my_tool":
        result = process(arguments["query"])
        return [TextContent(type="text", text=result)]

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

Config for Custom Server

json
{
  "my-custom-server": {
    "command": "python",
    "args": ["/path/to/my_server.py"]
  }
}

Custom MCP Server (TypeScript)

Setup

bash
npm init -y
npm install @modelcontextprotocol/sdk

Basic Server

typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "my_tool",
    description: "Does something",
    inputSchema: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_tool") {
    return { content: [{ type: "text", text: "Result" }] };
  }
});

new StdioServerTransport().connect(server);

Debugging

Test Server Manually

bash
# Run server directly
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check logs (Claude Desktop)
tail -f ~/Library/Logs/Claude/mcp*.log

Common Issues

  1. Server not starting: Check command path and permissions
  2. Auth errors: Verify env variables are set
  3. Timeout: Server may be slow to initialize
  4. Path issues: Use absolute paths

Reference

Full server list and advanced configuration: references/servers.md