install-mcpcat-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrate MCPCat into a Python MCP Server

将MCPCat集成到Python MCP服务器

MCPCat is a one-line SDK integration. It automatically tracks all tool calls, sessions, and user intent. You do NOT add tracking code inside tool functions — MCPCat hooks into the server at the protocol level.

MCPCat是只需一行代码即可集成的SDK。它会自动追踪所有工具调用、会话和用户意图。无需在工具函数内部添加追踪代码——MCPCat会在协议层面与服务器挂钩。

Step 1: Find the MCP server

步骤1：找到MCP服务器

Search all

.py

files for these import patterns (check in order):

from mcp.server.fastmcp import FastMCP

from mcp.server import FastMCP

— Official FastMCP

```
from fastmcp import FastMCP
```
— Community FastMCP (different package, needs
```
mcpcat[community]
```
)

from mcp.server.lowlevel import Server

from mcp.server import Server

— Low-level Server

In the matched file, find the server variable assignment (e.g.,

server = FastMCP(...)

app = Server(...)

). Store the variable name.

mcpcat.track

is already present in the file, tell the user MCPCat is already integrated and stop.

If multiple server instantiations exist, ask the user which one to instrument.

在所有

.py

文件中搜索以下导入模式（按顺序检查）：

from mcp.server.fastmcp import FastMCP

或

from mcp.server import FastMCP

——官方FastMCP

```
from fastmcp import FastMCP
```
——社区版FastMCP（不同的包，需要安装
```
mcpcat[community]
```
）

from mcp.server.lowlevel import Server

或

from mcp.server import Server

——底层Server

在匹配的文件中，找到服务器变量的赋值语句（例如

server = FastMCP(...)

或

app = Server(...)

），记录变量名称。

如果文件中已存在

mcpcat.track

，则告知用户MCPCat已完成集成并停止操作。

如果存在多个服务器实例化语句，请询问用户需要为哪一个添加监控。

Step 2: Get the project ID

步骤2：获取项目ID

If the user didn't provide a project ID (format:

proj_

followed by characters), ask them:

What is your MCPCat project ID? (format: proj_xxxxx) Create a free account at https://mcpcat.io to get one.

如果用户未提供项目ID（格式为

proj_

后跟字符），请询问他们：

你的MCPCat项目ID是什么？（格式：proj_xxxxx）可访问https://mcpcat.io创建免费账户获取。

Step 3: Check peer dependency

步骤3：检查依赖版本

Check the project's

pyproject.toml

requirements.txt

for the MCP SDK version:

Official MCP (
```
from mcp.server...
```
): Requires
```
mcp >= 1.2.0
```
. If older, tell the user to upgrade.
Community FastMCP (
```
from fastmcp import FastMCP
```
): Requires
```
fastmcp >= 2.7.0
```
and NOT
```
2.9.*
```
. If older or on 2.9.x, tell the user to upgrade/change version.

If the version can't be determined from project files, run

pip show mcp

pip show fastmcp

to check the installed version.

检查项目的

pyproject.toml

或

requirements.txt

文件中的MCP SDK版本：

官方MCP（导入语句为
```
from mcp.server...
```
）：要求
```
mcp >= 1.2.0
```
。如果版本较旧，请告知用户进行升级。
社区版FastMCP（导入语句为
```
from fastmcp import FastMCP
```
）：要求
```
fastmcp >= 2.7.0
```
且不能是
```
2.9.*
```
版本。如果版本较旧或为2.9.x版本，请告知用户升级或更换版本。

如果无法从项目文件中确定版本，可运行

pip show mcp

或

pip show fastmcp

来检查已安装的版本。

Step 4: Install the package

步骤4：安装包

First check if

mcpcat

(or

mcpcat[community]

) is already listed in the project's dependency files (

pyproject.toml

requirements.txt

). If it is already listed, skip this step.

If not listed, detect the package manager and install:

Indicator	Command
`uv.lock` or `[tool.uv]` in pyproject.toml	`uv add mcpcat`
`poetry.lock`	`poetry add mcpcat`
`Pipfile`	`pipenv install mcpcat`
`requirements.in`	Add `mcpcat` to `requirements.in` , then `pip-compile requirements.in`
Otherwise	Check the project's README and other `.md` files for dependency management instructions, then install accordingly

For community FastMCP (import is

from fastmcp import FastMCP

), use

"mcpcat[community]"

instead of

mcpcat

in all install commands above.

uv add

poetry add

, and

pipenv install

handle dependency files automatically — no extra step needed for those. For

pip-tools

, the dependency is tracked in

requirements.in

. For other package managers, ensure

mcpcat

is added to the appropriate dependency file after installation.

首先检查项目的依赖文件（

pyproject.toml

或

requirements.txt

）中是否已列出

mcpcat

（或

mcpcat[community]

）。如果已列出，则跳过此步骤。

如果未列出，检测包管理器并执行安装：

识别标识	命令
`uv.lock` 或 `pyproject.toml` 中包含 `[tool.uv]`	`uv add mcpcat`
`poetry.lock`	`poetry add mcpcat`
`Pipfile`	`pipenv install mcpcat`
`requirements.in`	将 `mcpcat` 添加到 `requirements.in` ，然后运行 `pip-compile requirements.in`
其他情况	查看项目的README和其他 `.md` 文件中的依赖管理说明，然后按说明安装

对于社区版FastMCP（导入语句为

from fastmcp import FastMCP

），请将上述所有安装命令中的

mcpcat

替换为

"mcpcat[community]"

。

uv add

、

poetry add

和

pipenv install

会自动处理依赖文件——使用这些工具时无需额外步骤。对于

pip-tools

，依赖会被记录在

requirements.in

中。对于其他包管理器，安装后请确保

mcpcat

已添加到相应的依赖文件中。

Step 5: Add the integration code

步骤5：添加集成代码

Make two edits to the server file. Do NOT add tracking code inside tool functions — MCPCat does this automatically.

1. Imports — add at the top with other imports:

python

import os
import mcpcat
from mcpcat import MCPCatOptions

Add

import os

only if not already present.

2. Track call — add AFTER the server variable is created, BEFORE

server.run()

or ASGI mounting:

python

mcpcat.track(SERVER_VAR, "PROJECT_ID", MCPCatOptions(
    debug_mode=os.getenv("MCPCAT_DEBUG_MODE", "false").lower() in ("true", "1", "yes", "on")
))

Replace

SERVER_VAR

with the actual variable name (e.g.,

server

app

mcp

) and

PROJECT_ID

with the user's project ID.

对服务器文件进行两处修改。无需在工具函数内部添加追踪代码——MCPCat会自动完成此操作。

1. 导入语句——在文件顶部与其他导入语句一起添加：

python

import os
import mcpcat
from mcpcat import MCPCatOptions

仅当

import os

未在文件中存在时才添加它。

2. Track调用——在服务器变量创建之后、

server.run()

或ASGI挂载之前添加：

python

mcpcat.track(SERVER_VAR, "PROJECT_ID", MCPCatOptions(
    debug_mode=os.getenv("MCPCAT_DEBUG_MODE", "false").lower() in ("true", "1", "yes", "on")
))

将

SERVER_VAR

替换为实际的变量名称（例如

server

、

app

、

mcp

），将

PROJECT_ID

替换为用户的项目ID。

Placement rules

放置规则

MUST be after the line that creates the server (e.g.,
```
server = FastMCP(...)
```
)
MUST be before
```
server.run()
```
or any ASGI app mounting
Can go before or after
```
@server.tool()
```
definitions — both work. Before is canonical.
If server is created inline (e.g.,
```
export default FastMCP(...)
```
), refactor to assign to a variable first

必须在创建服务器的语句之后（例如
```
server = FastMCP(...)
```
）
必须在
```
server.run()
```
或任何ASGI应用挂载之前
可以在
```
@server.tool()
```
定义之前或之后——两种方式都有效。通常放在定义之前。
如果服务器是内联创建的（例如
```
export default FastMCP(...)
```
），请先重构为赋值给一个变量

Why this MCPCatOptions pattern is required

为何需要这种MCPCatOptions模式

The

MCPCAT_DEBUG_MODE

env var IS read at module load time, but

mcpcat.track()

calls

set_debug_mode(options.debug_mode)

which overrides it. Since

MCPCatOptions.debug_mode

defaults to

False

, calling

track()

without explicit options silently disables env-var-based debug mode. The pattern above preserves env var control. Debug logs are written to

~/mcpcat.log

MCPCAT_DEBUG_MODE

环境变量会在模块加载时读取，但

mcpcat.track()

会调用

set_debug_mode(options.debug_mode)

来覆盖它。由于

MCPCatOptions.debug_mode

默认为

False

，如果调用

track()

时未传入显式选项，会静默禁用基于环境变量的调试模式。上述模式保留了环境变量的控制权限。调试日志会写入

~/mcpcat.log

。

Complete example

完整示例

A typical FastMCP server after integration:

python

import os
import mcpcat
from mcpcat import MCPCatOptions
from mcp.server.fastmcp import FastMCP

server = FastMCP("weather-server", version="2.1.0")

mcpcat.track(server, "proj_abc123", MCPCatOptions(
    debug_mode=os.getenv("MCPCAT_DEBUG_MODE", "false").lower() in ("true", "1", "yes", "on")
))

@server.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: 72F, sunny"

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

Notice: zero tracking code inside

get_weather

. MCPCat automatically captures all tool calls at the protocol level.

集成后的典型FastMCP服务器：

python

import os
import mcpcat
from mcpcat import MCPCatOptions
from mcp.server.fastmcp import FastMCP

server = FastMCP("weather-server", version="2.1.0")

mcpcat.track(server, "proj_abc123", MCPCatOptions(
    debug_mode=os.getenv("MCPCAT_DEBUG_MODE", "false").lower() in ("true", "1", "yes", "on")
))

@server.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: 72F, sunny"

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

注意：

get_weather

函数内部没有任何追踪代码。MCPCat会在协议层面自动捕获所有工具调用。

Step 6: Verify

步骤6：验证

Read the modified file and confirm the import and
```
track()
```
call are correctly placed.
Run
```
python -c "import mcpcat"
```
to verify the package is importable.
If the project uses a linter (ruff, mypy, pyright), run it if configured.
Tell the user:

MCPCat is integrated. Your server will automatically report analytics when it runs. Enable debug logging:
MCPCAT_DEBUG_MODE=true python your_server.py
(logs to ~/mcpcat.log) View your dashboard at https://app.mcpcat.io

查看修改后的文件，确认导入语句和
```
track()
```
调用的位置正确。
运行
```
python -c "import mcpcat"
```
以验证包可被正常导入。
如果项目使用了代码检查工具（ruff、mypy、pyright），若已配置则运行该工具。
告知用户：

MCPCat已集成完成。你的服务器运行时会自动上报分析数据。启用调试日志：
MCPCAT_DEBUG_MODE=true python your_server.py
（日志会写入~/mcpcat.log）访问https://app.mcpcat.io查看你的仪表盘

Common mistakes

常见错误

Mistake	Fix
Adding tracking code inside each tool function	MCPCat is automatic. Remove manual tracking. Only `mcpcat.track()` is needed.
Initializing MCPCat before server creation	`mcpcat.track(server, ...)` needs the server variable. Call it AFTER `server = FastMCP(...)` .
Using `pip install mcpcat` for community FastMCP	Use `pip install "mcpcat[community]"` when import is `from fastmcp import FastMCP` .
Using `MCPCatOptions()` without `debug_mode`	Defaults to `debug_mode=False` , overriding the env var. Pass it explicitly.
Using wrong env var name	The env var is `MCPCAT_DEBUG_MODE` , not `MCPCAT_DEBUG` .

错误	修复方法
在每个工具函数内部添加追踪代码	MCPCat是自动追踪的。移除手动添加的追踪代码。只需保留 `mcpcat.track()` 即可。
在服务器创建之前初始化MCPCat	`mcpcat.track(server, ...)` 需要服务器变量。请在 `server = FastMCP(...)` 之后调用它。
为社区版FastMCP使用 `pip install mcpcat`	当导入语句为 `from fastmcp import FastMCP` 时，请使用 `pip install "mcpcat[community]"` 。
使用 `MCPCatOptions()` 但未传入 `debug_mode`	默认 `debug_mode=False` ，会覆盖环境变量。请显式传入该参数。
使用错误的环境变量名称	正确的环境变量名称是 `MCPCAT_DEBUG_MODE` ，而非 `MCPCAT_DEBUG` 。