AI导哈

TinyDB MCP服务器

一个为TinyDB文档数据库操作准备的生产级MCP服务器，适用于AI助手集成和小型应用开发。

  • by Will-Conklin
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Will-Conklin/mcp-demo

使用说明

🗄️ TinyDB MCP服务器

用于TinyDB文档数据库操作的生产就绪模型上下文协议（MCP）服务器。

📋 概述

此MCP服务器使AI助手和其他MCP客户端能够使用以下命令执行文档数据库操作 TinyDB，一个轻量级的基于JSON的Python数据库。

graph LR
    A[Claude Desktop] -->|MCP Protocol| B[TinyDB MCP Server]
    B -->|Read/Write| C[(TinyDB JSON)]
    B -->|Tools| D[CRUD Operations]
    B -->|Resources| E[Database Stats]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#bfb,stroke:#333,stroke-width:2px

非常适合：

  • 🎯 本地开发和原型制作
  • 🤖 通过MCP集成AI助手
  • 📦 小规模应用
  • 🧪 测试和实验

特性

工具

工具 说明
insert_document 将文档插入表格
查询文档 使用可选字段/值过滤查询文档
update_文档 更新符合特定条件的文档
删除文档 删除文档（可选过滤）
list_tables 列出数据库中的所有可用表

资源

资源URI 描述
tinydb://stats 数据库统计信息，包括文档计数
tinydb://tables 包含元数据的所有表的列表
tinydb://table/{table_name} 特定表格的内容

安装

  1. 克隆存储库并导航到项目目录

  2. 使用uv安装依赖项：

uv sync

用法

运行服务器

选项1：直接Python（开发）

使用stdio传输启动MCP服务器：

python main.py

选项2：Docker（生产）

在容器中运行服务器：

# Build and start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

# Or build and run directly with Docker
docker build -t mcp-tinydb-server .
docker run -it --rm \
  -v tinydb-data:/data \
  -e TINYDB_PATH=/data/tinydb_data.json \
  mcp-tinydb-server

Docker的好处：

  • 孤立的环境
  • 跨系统的一致部署
  • 通过卷进行持久数据存储
  • 无需本地Python/依赖设置
  • 非root用户执行以确保安全

配置MCP客户端

将此服务器添加到MCP客户端配置中。配置文件位置因操作系统而异：

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

推荐：Docker配置 （不需要Python/依赖项）：

首先，构建Docker镜像：

docker build -t mcp-tinydb-server .

然后添加到Claude Desktop配置中：

{
  "mcpServers": {
    "tinydb": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name", "mcp-tinydb-claude",
        "-v", "mcp-tinydb-data:/data",
        "mcp-tinydb-server"
      ]
    }
  }
}

Docker配置的好处：

  • 无需本地Python或uv安装
  • 孤立的环境
  • 通过Docker卷持久化数据
  • 自动清理 --rm 旗帜
  • 易于更新（只需重建图像）

替代方案：紫外线局部开发:

{
  "mcpServers": {
    "tinydb": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/mcp-tinydb-server",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

对当地发展至关重要:

  • 替换 /path/to/uv 使用您的紫外线安装路径（用 which uv 在终端）
  • 替换 /path/to/mcp-tinydb-server 使用您的项目目录
  • 像Claude Desktop这样的GUI应用程序不会继承终端的PATH，因此请使用绝对路径

更新配置后：

  1. 保存文件
  2. 重新启动克劳德桌面
  3. TinyDB工具和资源将出现在MCP工具列表中

示例操作

插入文档

Use the insert_document tool:
- data: {"name": "Alice", "age": 30, "city": "NYC"}
- table: "users"

查询文档

Use the query_documents tool:
- field: "city"
- value: "NYC"
- table: "users"

Or get all documents:
- table: "users"
(leave field and value empty)

更新文档

Use the update_documents tool:
- field: "name"
- value: "Alice"
- updates: {"age": 31}
- table: "users"

删除文档

Use the delete_documents tool:
- field: "name"
- value: "Alice"
- table: "users"

列表表格

Use the list_tables tool (no parameters needed)

查看数据库统计信息

Read the tinydb://stats resource

查看表格内容

Read the tinydb://table/users resource (replace 'users' with your table name)

数据库

服务器创建 tinydb_data.json 文件来存储所有数据。此文件在首次使用时自动创建。

地方发展： 数据库存储在项目根目录中

Docker： 数据库存储在Docker卷中 /data/tinydb_data.json 在容器内部，在容器重新启动时持续存在

配置： 集 TINYDB_PATH 用于自定义数据库位置的环境变量

项目结构

mcp-tinydb-server/
├── src/
│   ├── __init__.py
│   └── mcp_tinydb_server.py   # Main server implementation
├── tests/                      # Test suite
│   ├── __init__.py
│   ├── test_tinydb_manager.py
│   ├── test_tools.py
│   └── test_resources.py
├── main.py                     # Entry point
├── pyproject.toml             # Dependencies
├── tinydb_data.json           # Database file (created on first use)
└── README.md                  # This file

发展

需求

  • Python 3.14+
  • mcp[cli]>=1.23.1
  • TinyDB>=4.8.0

VS代码任务

此项目包括用于常见操作的VS Code任务。通过以下方式运行任务 Cmd+Shift+P → “任务：运行任务”：

快速命令：

  • ⇧⌘B -构建Docker镜像
  • 测试面板-使用UI运行测试
  • F5 -调试MCP服务器或测试

可用任务：

  • 测试：运行所有测试，带覆盖率运行
  • 代码质量：Lint、Fix、带Ruff的格式、类型检查（ty）
  • Docker：构建、启动、停止、查看日志
  • 开发：运行MCP服务器，安装依赖项

看 .vscode/tasks.json 查看可用任务的完整列表。

测试

使用pytest运行测试套件：

uv run pytest tests/ -v

该测试套件包括46个测试，涵盖：

  • TinyDBManager类（9个测试）
  • 所有MCP工具（23项测试）
  • 所有MCP资源（14项测试）

您还可以使用MCP检查器或任何MCP客户端测试服务器。服务器通过stdio传输运行，并遵循MCP规范。

故障排除

Claude Desktop中出现“生成进程失败”错误

如果您在Claude Desktop日志中看到此错误(~/Library/Logs/Claude/mcp-server-tinydb.log 在macOS上）：

Failed to spawn process: No such file or directory

解决方案：使用绝对路径 uv 配置中的命令：

# Find your uv path
which uv

# Use that full path in claude_desktop_config.json
# Example: /Users/YOUR_USERNAME/.local/bin/uv

GUI应用程序无法访问终端的PATH环境变量，因此相关命令如 uv 找不到。

查找克劳德桌面日志

  • macOS: ~/Library/Logs/Claude/mcp-server-tinydb.log
  • 视窗: %APPDATA%\Claude\logs\mcp-server-tinydb.log
  • Linux: ~/.config/Claude/logs/mcp-server-tinydb.log

许可证

有关详细信息，请参阅LICENSE文件。

相关 MCP