freebase.cloud

free-database-mcp-server

本指南介绍如何将任意 MCP 客户端连接到 免费的云数据库。涵盖 15 种引擎，采用统一的端点格式，每个连接提供四种工具；并列出每种引擎的版本和方言、每个客户端的配置文件及其确切的键名，以及根据这些键名容易导致的错误整理的故障排查部分。如需按任务了解操作流程，可参阅配套代码库 mcp-database-server-free，其中按工作内容进行了组织。

跳转至：引擎 · 访问模型 · 工具 · 客户端设置 · 故障排查 · 选择引擎 · 示例

引擎

引擎	版本	方言	支持的 CLI	端口	访问方式
PostgreSQL	16.2	SQL	psql	5432	原生 TCP + HTTP + MCP
MySQL	8.0.36	SQL	mysql	3306	HTTP + MCP
MongoDB	7.0.4	文档 / NoSQL	mongosh	27017	原生 TCP + HTTP + MCP
Redis	7.2.3	键值 / 内存	redis-cli	6379	原生 TCP + HTTP + MCP
SQLite	3.45.1	SQL	sqlite3	—	HTTP + MCP
Apache Cassandra	4.1.4	宽列 / CQL	cqlsh	9042	HTTP + MCP
DynamoDB	2024.1	键值 / 文档	aws CLI	—	HTTP + MCP
ClickHouse	24.1.5	列式 / OLAP SQL	clickhouse-client	9000	HTTP + MCP
Elasticsearch	8.12.0	搜索 / 查询 DSL	curl / ES 客户端	9200	HTTP + MCP
Neo4j	5.17.0	图 / Cypher	cypher-shell	7687	HTTP + MCP
MariaDB	11.3.2	SQL	mysql	3306	HTTP + MCP
InfluxDB	2.7.4	Flux / InfluxQL	influx	8086	HTTP + MCP
Prometheus	2.50.1	PromQL	promtool / curl	9090	HTTP + MCP
TimescaleDB	2.14.2	SQL（PostgreSQL + Timescale）	psql	5432	HTTP + MCP
CockroachDB	23.2.4	SQL（兼容 PostgreSQL）	cockroach sql / psql	26257	HTTP + MCP

端口是该引擎协议通常使用的端口——它用于说明适用的方言和客户端工具，并不表示有套接字正在侦听。每种引擎都有一个页面，地址为 https://freebase.cloud/free-<slug>-cloud-instance（slug：postgresql、mysql、mongodb、 redis、sqlite、cassandra、dynamodb、clickhouse、elasticsearch、neo4j、mariadb、 influxdb、prometheus、timescaledb、cockroachdb），另有 Claude 指南，地址为 https://freebase.cloud/how-to-connect-claude-to-<slug>——例如 Elasticsearch 实例页面。

访问方式

有两种不同的接入路径。大多数配置问题都源于混淆了它们。

原生线路协议——三种引擎。 PostgreSQL、Redis 和 MongoDB 支持通过其原生协议连接的真实驱动：通过 RESP2 使用 psql/libpq/Prisma/SQLAlchemy/pgx、redis-cli/ioredis/redis-py/Lettuce，通过 OP_MSG 使用 mongosh/Mongoose/原生驱动。不会进行代理或重塑。

postgresql://freebase@HOST:5432/DBNAME    redis://HOST:6379    mongodb://HOST:27017/DBNAME

HTTP 和 MCP——全部十五种。 其余十二种通过托管 HTTP 查询 API和 MCP 接入。它们使用各自的方言——Cassandra 使用 CQL，Neo4j 使用 Cypher，InfluxDB 使用 Flux——但传输方式是 HTTP，而不是原始套接字。如果你要接入 AI 助手，无论使用哪种引擎，都应选择这条路径，因为它们的接入方式完全相同：

https://freebase.cloud/api/mcp/YOUR_TOKEN

令牌位于URL 路径中，因此本文档中不会出现 Authorization 标头。由此可知，URL 就是凭据。不要提交它，不要将它粘贴到共享配置中；如果已经这样做，请通过设置 → MCP轮换令牌。传输方式为可流式 HTTP，它在内部使用服务器发送事件来传输流式响应——这与已弃用的 HTTP+SSE 传输不同，后者使用单独的 /sse 端点和 POST /messages。如果客户端提供这两种方式，请选择可流式方式。

四种工具

每个连接有四种工具，使用你选择的连接名称作为前缀，而不是引擎名称。名为 db 的连接会提供：

工具	用途	在不同引擎中的含义
db_query	使用引擎的原生语言读取数据	SQL · CQL · Cypher · Flux · PromQL · ES 查询 DSL · Mongo find/aggregate · Redis 命令
db_store	插入、插入或更新、写入	INSERT · MERGE · _bulk · 行协议 · SET · PutItem
db_list_tables	枚举容器	表 · 集合 · 键空间 · 索引 · 测量值 · 指标名称 · 键
db_annotate_table	为容器添加说明	让模型了解各列的含义

有两种引擎还提供辅助工具：PostgreSQL 提供 pg_dump、pg_restore 和 pg_tables；SQLite 提供 sqlite_master 和 sqlite_version。

使用 annotate_table。 这是本文档中投入五分钟、回报最高的操作。即使模型能列出你的表，它仍然需要猜测 status 存储的是 'active' 还是 1，amount_cents 的单位是美分还是美元，以及是否应通过 deleted_at IS NULL 进行筛选。每张表只需撰写一段说明；说明会保存在连接中，并适用于所有使用该令牌的客户端中的每次对话。

快速入门

在 freebase.cloud 控制面板注册（无需银行卡），创建会话并选择引擎，然后前往设置 → MCP → 新建令牌 → 选择连接 → 复制 URL。在配置客户端之前，先确认连接正常——如果打印出四个工具名称，就说明其他问题都是配置问题：

export FREEBASE_MCP_URL="https://freebase.cloud/api/mcp/YOUR_TOKEN"
python3 examples/list_tools.py

客户端配置

客户端	配置位置	顶层键	URL 键	type 值
Claude Desktop / web / Cowork	仅限 UI	—	—	—
Claude Code	.mcp.json / 用户配置	mcpServers	url	"http"（必填）
ChatGPT	UI（开发者模式）	—	—	—
OpenAI Responses API	请求正文	tools[]	server_url	"mcp"
Cursor	~/.cursor/mcp.json 或 .cursor/mcp.json	mcpServers	url	完全省略
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers	serverUrl	—
VS Code / Copilot Chat	.vscode/mcp.json	servers	url	"http"
Zed	settings.json	context_servers	url	—
Cline	MCP 设置 JSON	mcpServers	url	"streamableHttp"
Roo Code	.roo/mcp.json	mcpServers	url	"streamable-http"
Gemini CLI	settings.json	mcpServers	httpUrl	—
Warp	Settings → AI → Manage MCP servers	(无)	url	—
n8n	MCP Client Tool 节点	—	Endpoint 字段	HTTP Streamable
LangChain / LlamaIndex	Python	—	url	"http"

Claude Desktop、Claude web、Cowork

仅限 UI。Settings（⌘, / Ctrl+,）→ Connectors（较新版本中为 Customize → Connectors）→ Add custom connector → 粘贴 URL → Add。在对话中点击撰写框里的 + 按钮启用。Free、Pro、Max、Team 和 Enterprise 均可使用；Free 账户只能添加一个自定义连接器。 claude_desktop_config.json 无法表示远程 HTTP MCP 服务——指导你在其中添加服务的文章发布于支持流式 HTTP 之前。这些步骤的特定引擎版本见 如何将 Claude 连接到 PostgreSQL 及其他 slug 对应的指南。

Claude Code

claude mcp add --transport http db https://freebase.cloud/api/mcp/YOUR_TOKEN
#   --scope project  writes .mcp.json (commit it, minus the token) | --scope user = all projects

{ "mcpServers": { "db": { "type": "http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

streamable-http 可作为 http 的别名。

ChatGPT

Settings → Apps → Advanced settings → 启用开发者模式 → Apps → Create → 粘贴 端点 → Auth 选择 None → Scan Tools → Create。也请查看 Settings → Connectors；OpenAI 的两个文档页面对该选项的位置说法不一。Pro、Plus、Business、Enterprise 和 Edu 均有开发者模式文档说明；完整写入权限目前正逐步向 Business、Enterprise 和 Edu 工作区开放，因此部分方案目前只能只读访问工具。

OpenAI Responses API

{
  "model": "gpt-5.6",
  "tools": [{
    "type": "mcp",
    "server_label": "db",
    "server_description": "Free cloud database — query and store structured data.",
    "server_url": "https://freebase.cloud/api/mcp/YOUR_TOKEN",
    "require_approval": "never"
  }],
  "input": "List the tables in my database."
}

Cursor、Windsurf、VS Code、Zed

// ~/.cursor/mcp.json  or  .cursor/mcp.json     — NO "type" key
{ "mcpServers": { "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

// ~/.codeium/windsurf/mcp_config.json          — the key is serverUrl
{ "mcpServers": { "db": { "serverUrl": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

// .vscode/mcp.json                             — top-level key is "servers"
{
  "inputs": [{ "type": "promptString", "id": "fb-token", "description": "freebase.cloud MCP token", "password": true }],
  "servers": { "db": { "type": "http", "url": "https://freebase.cloud/api/mcp/${input:fb-token}" } }
}

// Zed settings.json                            — "context_servers", not "mcpServers"
{ "context_servers": { "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

Windsurf 现在在 docs.devin.ai 上以“Devin Desktop”之名提供文档；Enterprise 用户必须先在设置中启用 MCP。在 VS Code 中，命令面板 → MCP: Add Server 会生成该文件，而 inputs 块会将令牌排除在文件之外，使配置可以提交到代码库。

Cline 和 Roo Code

传输方式相同，拼写不同，二者无法互相回退。

// Cline — camelCase
{ "mcpServers": { "db": { "type": "streamableHttp", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN", "disabled": false, "autoApprove": [] } } }

// Roo Code, .roo/mcp.json — kebab-case
{ "mcpServers": { "db": { "type": "streamable-http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

Gemini CLI

gemini mcp add --transport http db https://freebase.cloud/api/mcp/YOUR_TOKEN

{ "mcpServers": { "db": { "httpUrl": "https://freebase.cloud/api/mcp/YOUR_TOKEN", "timeout": 5000 } } }

在 settings.json 中，键名是 httpUrl。普通的 url 表示 SSE——配置错误会导致服务看似已连接，却始终不返回工具。面向消费者的 Gemini 应用不支持自定义 MCP 服务；只有 Gemini Enterprise 支持。

Warp 和 n8n

Warp：Settings → AI → Manage MCP servers → “Streamable HTTP or SSE Server (URL)”。其粘贴框只接受服务对象本身，不需要 mcpServers 包装：

{ "db": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } }

n8n：MCP Client Tool 节点（1.104.0+）。Server Transport → HTTP Streamable，Endpoint → 你的 URL，Authentication → None。已发布的文档页面仍只显示旧的“SSE Endpoint”字段；当前版本的节点已有传输方式下拉菜单。

LangChain 和 LlamaIndex

from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({"db": {"transport": "http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN"}})
tools = await client.get_tools()

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
tools = await McpToolSpec(client=BasicMCPClient("https://freebase.cloud/api/mcp/YOUR_TOKEN")).to_tool_list_async()

mcp-remote（仅用作回退方案）

适用于仅支持 stdio 的客户端。需要 Node；其 README 称该工具仍处于实验阶段，因此只要客户端支持原生 HTTP，就应优先使用原生支持。

{ "mcpServers": { "db": { "command": "npx", "args": ["-y", "mcp-remote", "https://freebase.cloud/api/mcp/YOUR_TOKEN", "--transport", "http-only"] } } }

配置故障排查

症状	原因	修复方法
Claude Code 启动后立即报错	存在 url，但缺少 type	添加 "type": "http"。这是硬性错误，不是警告
Cursor 拒绝该条目或忽略该服务	添加了 "type" 键	删除它。在 Cursor 中，url 的存在表示这是远程服务
VS Code 始终无法识别该服务	配置使用了 mcpServers	.vscode/mcp.json 中的顶层键是 servers
Windsurf 将该服务显示为未配置	使用了 url	键名应为 serverUrl
Zed 忽略该文件	使用了 mcpServers	Zed 的键名是 context_servers
Gemini CLI 已连接，但未列出任何工具	使用了 url	使用 httpUrl。普通的 url 会选择 SSE 传输方式
Cline 报告未知传输方式	使用了 streamable-http	Cline 要求使用 streamableHttp（驼峰命名法）
Roo Code 报告未知传输方式	使用了 streamableHttp	Roo 要求使用 streamable-http（短横线命名法）
Warp 拒绝粘贴的 JSON	包含了 mcpServers 包装层	仅粘贴内部的服务对象
Claude Desktop 无法在 JSON 中找到该服务	此处不支持远程 HTTP 服务	请改为通过“设置 → 连接器”添加；请注意，Free 版最多支持一个连接器
ChatGPT 扫描到工具，但无法写入	你的方案尚未开放写入权限	读取功能可用；请检查你的工作区类型
工具显示的名称与预期不符	名称带有你的连接名称，而非引擎名称	重命名连接，或直接使用现有名称
端点返回 404	令牌已撤销，或复制粘贴时丢失了字符	前往“设置 → MCP”重新签发
curl 可用，但客户端失败	客户端读取的配置文件与你编辑的不同	检查用户级与项目级路径

选择引擎

通用关系型数据库 → PostgreSQL（也是唯一支持通过 MCP 执行转储／还原的引擎）。已有 MySQL 架构、PHP 或 WordPress → MySQL；如果需要序列、系统版本化表和动态列，则选择 MariaDB。灵活文档和 Mongoose → MongoDB。缓存、会话、计数器、速率限制以及任何带 TTL 的数据 → Redis。小型且架构要求不高 → SQLite。多行数据分析 → ClickHouse。全文搜索和排名 → Elasticsearch。关联数据、推荐、Agent 记忆 → Neo4j。设备指标 → InfluxDB；导出器和客户端库产生的指标 → Prometheus；与关系型表配合使用 → TimescaleDB。大规模宽列存储或学习 CQL → Cassandra。针对 AWS SDK 代码采用单表设计 → DynamoDB。默认采用可串行化隔离级别的分布式 SQL → CockroachDB。

示例

examples/list_tools.py 会打印每个工具及其输入架构——请先运行它。dialects.json 包含全部 15 种引擎的读写语句，examples/clients/ 中则有可直接复制的十种客户端配置文件。

node examples/roundtrip.mjs postgresql         # end-to-end write + read
node examples/roundtrip.mjs redis --keep       # leave the data behind

roundtrip.mjs 会写入书签记录、读回记录，并报告读回的内容是否与写入的一致。分别针对两种引擎运行它，看看它们之间有多少差异——又有多少相同。

限制

免费层适用于开发、原型设计和小型生产工作负载。各引擎以上表所列版本运行，并提供其真实功能集：PostgreSQL 的事务、MongoDB 的聚合管道、ClickHouse 的 MergeTree、Neo4j 的 Cypher 和 APOC，以及 Elasticsearch 的聚合框架。此处不承诺 SLA、正常运行时间、备份保证或存储容量，因为这些数据均未经核实——控制面板会显示当前配额。请将任何无法承受丢失的数据视为需要自行备份。对于生产规模的工作负载、专用资源和支持服务，供应商自有的托管服务仍是合适的选择。

链接

freebase.cloud · MCP 规范（修订版 2026-07-28）· 传输参考

---

所属关系。 freebase.cloud 是一项独立服务，与 Anthropic、OpenAI、Google、Microsoft、Anysphere、Codeium、Zed Industries、Warp、n8n、Oracle、MongoDB, Inc.、Redis Ltd.、Elasticsearch B.V.、Neo4j, Inc.、InfluxData、ClickHouse, Inc.、Apache 软件基金会、AWS、Timescale, Inc.、Cockroach Labs 或 PostgreSQL 全球开发组均无隶属关系。