MCP Localbridge

MCP本地桥

英语| 中文

一种生产就绪的MCP（模型上下文协议）服务器实现，提供数据库查询、缓存和智能分析功能。

概述

MCP LocalBridge是一个高性能的MCP服务器 mcp走，为LLM应用程序（如Vibe Coding、Claude Desktop等）提供安全高效的数据访问。

核心功能

• 🔐 安全第一：所有数据库查询都使用参数化查询来防止SQL注入
• 🚀 多个传输：支持Stdio、SSE（基于HTTP的流式传输）和InProcess传输
• 💾 多数据库：MySQL、PostgreSQL支持，易于扩展
• ⚡ Redis缓存：高性能缓存可提高查询效率
• 🔍 智能洞察：数据库模式分析、关系图、语义摘要
• 🐳 容器化：通过一个命令部署完全支持Docker
• 🧪 干运行模式：为了安全起见，预览SQL查询而不执行

快速开始

先决条件

• 转到1.24+
• MySQL或PostgreSQL（在主机上运行）
• Redis（可选，用于缓存）

重要：此项目不会自动启动数据库容器。您的主机上必须运行MySQL/PostgreSQL/Redis。

地方发展

1. 克隆仓库

git clone https://github.com/SkillingX/mcp-localbridge.git
cd mcp-localbridge

1. 安装依赖项

go mod download

1. 配置数据库连接

编辑 config/config.yaml 使用您的数据库凭据：

databases:
  mysql:
    - name: "mysql_main"
      enabled: true
      host: "localhost"  # or host.docker.internal in Docker
      port: 3306
      user: "your_username"
      password: "your_password"
      database: "your_database"

1. 构建并运行

# Option 1: Using Makefile
make build
make run

# Option 2: Direct execution
go run cmd/server/main.go -config config/config.yaml

# Option 3: Using script
./scripts/start.sh

Docker部署（推荐）

快速入门-3个步骤：

# 1. Start the container
make docker-run

# 2. Verify it's running
docker ps | grep mcp-localbridge

# 3. View logs
docker compose logs -f

有用命令：

make docker-run         # Build and start container
make docker-stop        # Stop container
make docker-update      # Rebuild and restart (after config changes)

可选-环境变量：

创建 .env 要覆盖配置的文件：

DB_MYSQL_HOST=host.docker.internal
DB_MYSQL_USER=root
DB_MYSQL_PASSWORD=your_password
# ... other variables

Linux用户：The docker-compose.yml 包含 extra_hosts 配置以支持 host.docker.internal.

验证安装

# Check container status
docker ps | grep mcp-localbridge

# Check SSE endpoint (should return 404, which is expected)
curl http://localhost:28028/api/mcp/sse

# View service logs
docker compose logs --tail=50

期待什么：

• MySQL、PostgreSQL、Redis初始化成功
• 运输开始： ["stdio","sse(0.0.0.0:28028)"]
• 日志中没有错误

配置

传输配置

在中启用任何传输组合 config/config.yaml:

transports:
  # Stdio transport - for local process communication
  stdio:
    enabled: true  # Standard I/O (for Claude Desktop, Cursor, VS Code)

  # SSE transport - HTTP-based streaming (RECOMMENDED for HTTP clients)
  # This is the primary HTTP transport for MCP protocol
  sse:
    enabled: true
    host: "0.0.0.0"
    port: 28028
    base_path: "/api/mcp"
    # Endpoints: GET  /api/mcp/sse (streaming)
    #            POST /api/mcp/message (messages)

  # HTTP transport - placeholder for future JSON-RPC over HTTP
  # Note: Use SSE transport for all HTTP-based MCP communication
  http:
    enabled: false  # Not implemented in mcp-go v0.11.0
    port: 28027

  # InProcess transport - for testing and embedded scenarios
  inprocess:
    enabled: false

重要：The SSE（服务器发送事件）传输是基于HTTP的标准协议 对于MCP。它通过HTTP提供实时流媒体，是以下情况的推荐选择：

• Docker部署
• 基于Web的客户端
• IDE集成（游标、VS代码）
• 远程服务器访问

数据库配置

支持多个数据库实例：

databases:
  mysql:
    - name: "mysql_main"
      enabled: true
      host: "${DB_MYSQL_HOST:-localhost}"
      # ... other configs

  postgres:
    - name: "postgres_main"
      enabled: false  # Disable unused databases
      # ...

安全配置

tools:
  db:
    default_dry_run: true  # Enable dry-run by default (recommended for production)
    max_rows: 1000         # Maximum rows to return
    query_timeout: 30      # Query timeout (seconds)

环境变量优先级

配置优先级： 环境变量>config.yaml

常见环境变量：

• DB_MYSQL_HOST, DB_MYSQL_PORT, DB_MYSQL_USER, DB_MYSQL_PASSWORD
• REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
• LOG_LEVEL：日志级别（调试/信息/警告/错误）
• TOOLS_DB_DRY_RUN：默认干运行模式

MCP工具

数据库工具

db_query

使用条件、分页和排序执行参数化数据库查询。

参数:

• database （必填）：数据库实例名称
• table （必填）：表名
• conditions （可选）：JSON WHERE条件，例如。， {"status":"active","age":25}
• limit, offset, order_by （可选）
• dry_run （可选）：在以下情况下返回SQL预览而不执行 true

示例:

{
  "database": "mysql_main",
  "table": "users",
  "conditions": "{\"status\":\"active\"}",
  "limit": "10",
  "dry_run": "true"
}

db_table_list

列出数据库中的所有表。

db_table_preview

预览表数据（默认值：前10行）。

Redis工具

redis_get, redis_set, redis_scan

Redis键值操作和扫描。

洞察工具

introspection

数据库模式自检：表、列、索引、外键。为性能而缓存。

semantic_summary

生成表数据的语义摘要，返回LLM提示模板供MCP客户端使用。

relationship

分析表之间的外键关系，生成关系图和LLM分析提示。

analytics

使用分组和筛选执行聚合查询（COUNT/SUM/AVG/MIN/MAX）。

metadata

检索表和列元数据（注释、描述等）。

发展

项目结构

mcp-localbridge/
├── cmd/
│   ├── server/          # MCP server entry point
│   └── client/          # MCP client entry point
├── config/              # Configuration management
├── server/              # MCP server core
├── transports/          # Transport layer implementations
├── db/                  # Database access layer
├── cache/               # Redis cache layer
├── tools/               # MCP tool implementations
├── insights/            # Intelligent analytics tools
├── tests/               # Unit tests
└── scripts/             # Helper scripts

运行测试

# Run all tests
make test

# Run tests with coverage report
make test-coverage

# View coverage
open coverage.html

代码质量

# Format code
make fmt

# Run go vet
make vet

# Run golangci-lint (requires installation)
make lint

连接到主机数据库

macOS/Windows（Docker桌面）

使用 host.docker.internal 直接：

databases:
  mysql:
    - host: "host.docker.internal"
      port: 3306

Linux

使用 host.docker.internal （在docker-compose.yml中配置为 extra_hosts)或主机IP：

databases:
  mysql:
    - host: "host.docker.internal"  # or "172.17.0.1", etc.
      port: 3306

确保您的数据库处于监听状态 0.0.0.0 而不是仅仅 127.0.0.1.

禁用干运行

要在生产环境中执行查询，请执行以下操作：

1. 配置文件：编辑 config/config.yaml

   tools:
     db:
       default_dry_run: false

1. 环境变量:

   export TOOLS_DB_DRY_RUN=false

1. 每次工具调用:

   {"dry_run": "false"}

IDE集成和Vibe编码设置

克劳德桌面/Claude应用程序配置

Claude Desktop可以使用Stdio传输连接到MCP服务器。

1. 获取服务器路径

   which mcp-server
   # or if using docker
   pwd  # Get your project directory

1. 编辑Claude桌面配置

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. 添加MCP本地网桥配置

   {
     "mcpServers": {
       "mcp-localbridge": {
         "command": "/path/to/mcp-server",
         "args": ["-config", "/path/to/config/config.yaml"],
         "env": {
           "LOG_LEVEL": "info",
           "DB_MYSQL_HOST": "localhost",
           "DB_MYSQL_USER": "root",
           "DB_MYSQL_PASSWORD": "your_password"
         }
       }
     }
   }

1. 在Claude Desktop中验证

- 重新启动克劳德桌面 - 当您与MCP服务器交互时，它将自动启动 - 检查服务器日志： docker compose logs -f （如果使用Docker）

光标IDE配置

Cursor通过SSE（基于HTTP）和Stdio传输支持MCP服务器。

快速配置：

将以下内容添加到光标MCP设置中：

苏格兰和南方能源公司运输（推荐）：

{
  "mcpServers": {
    "mcp-localbridge": {
      "type": "sse",
      "url": "http://localhost:28028/api/mcp/sse",
      "timeout": 30000
    }
  }
}

标准运输：

{
  "mcpServers": {
    "mcp-localbridge": {
      "command": "/path/to/mcp-server",
      "args": ["-config", "/path/to/config/config.yaml"]
    }
  }
}

选项1：使用SSE传输（建议用于Docker部署）

1. 启动启用SSE传输的MCP服务器

   # Using Docker (recommended)
   make docker-run

   # Or locally
   make run-server

确保在中启用了SSE config/config.yaml:

   transports:
     sse:
       enabled: true
       host: "0.0.0.0"
       port: 28028
       base_path: "/api/mcp"

1. 打开光标设置 → MCP服务器 → 添加服务器

1. 添加SSE配置 （见上文快速配置）

1. 验证连接

- 服务器应在Cursor的MCP面板中显示为“已连接” - 测试： db_table_list, db_table_preview

选项2：使用标准交通（当地开发）

对于具有直接进程通信的本地开发，请添加stdio配置（请参阅上面的快速配置）。

备注：Stdio需要本地二进制文件。对于Docker部署，使用SSE传输。

克劳德代码（VS代码扩展）配置

Claude Code可以通过Stdio或SSE传输使用MCP服务器。

选项1：使用标准交通（当地开发）

1. 安装Claude代码扩展 VS代码

1. 创建或编辑 .claude/mcp-config.json 在项目根目录中

   {
     "servers": [
       {
         "name": "mcp-localbridge",
         "command": "/path/to/bin/mcp-server",
         "args": ["-config", "/path/to/config/config.yaml"],
         "env": {
           "LOG_LEVEL": "info",
           "DB_MYSQL_HOST": "localhost"
         },
         "transport": "stdio"
       }
     ]
   }

选项2：使用SSE传输（Docker部署）

对于基于Docker的部署，使用SSE传输：

{
  "servers": [
    {
      "name": "mcp-localbridge",
      "type": "sse",
      "url": "http://localhost:28028/api/mcp/sse",
      "timeout": 30000
    }
  ]
}

用克劳德代码验证:

• 在Claude Code中打开MCP面板
• 应列出并连接服务器
• 测试可用工具： db_query, redis_get, introspection

IDE集成的快速Docker设置

使用Docker快速设置：

# Build and run the server
make docker-run

# Update server with config changes
make docker-update

# View logs
docker compose logs -f

# Stop server
make docker-stop

然后配置IDE以连接到：

• SSE（推荐）: http://localhost:28028/api/mcp/sse

- MCP的主要基于HTTP的传输 - 支持实时流媒体 - 适用于Docker部署

• Stdio（仅限本地）：直接过程沟通

- 命令： /path/to/bin/mcp-server -config /path/to/config/config.yaml - 最有利于当地发展 - 需要本地二进制构建

IDE连接故障排除

1. 连接被拒绝

- 验证服务器是否正在运行： docker ps 或 curl http://localhost:28027/health - 检查防火墙规则 - 确保端口号正确

1. 工具未显示

- 检查服务器日志： docker compose logs mcp-server - 验证数据库连接： docker compose logs | grep -i "error" - 确保config.yaml是有效的yaml

1. IDE中的数据库连接错误

- 验证数据库是否在主机上运行 - 检查中的配置凭据 config/config.yaml - 对于Docker：确保使用 host.docker.internal （macOS/Windows）或正确的主机IP（Linux）

1. 日志和调试

   # View real-time logs
   docker compose logs -f

   # Increase log level for debugging
   LOG_LEVEL=debug make docker-run

   # Check server health
   curl -v http://localhost:28027/health

安全最佳实践

1. ✅ 所有SQL查询都使用参数化查询 防止SQL注入
2. ✅ 默认情况下启用干运行模式，必须明确禁用
3. ✅ 查询超时控制 防止长时间运行的查询
4. ✅ 结果行限制 防止数据返回过多
5. ✅ 输入验证 用于表名、列名、聚合函数等。
6. ⚠️ 生产审核：在生产中，审计和记录所有数据库操作

常见问题解答

Q： 为什么我无法连接到数据库？

A： 请检查：

1. 数据库正在主机上运行
2. 防火墙允许连接
3. 数据库正在监听 0.0.0.0 （不只是 127.0.0.1)
4. Linux用户：验证 extra_hosts 配置

Q： 如何查看详细日志？

A： 设置要调试的日志级别：

logging:
  level: "debug"

或者使用环境变量： LOG_LEVEL=debug

Q： 支持哪些数据库？

A： 目前MySQL和PostgreSQL。通过实现以下功能，可以轻松添加其他数据库 db.Repository 界面。

贡献

欢迎问题和拉取请求！

许可证

MIT许可证

致谢

• mcp走 -模型上下文协议Go实现
• sqlx -Go数据库扩展库
• go redis -Redis Go客户端

______________________________________________________________________

备注：该项目是一个完整的工程实践示例，具有全面的错误处理、记录、测试和文档。适合学习MCP协议实现和Go项目工程实践。