内容
# Instagram MCP 服务器
本MCP（模型内容协议）服务器通过FastMCP的STDIO传输模式提供对Instagram API功能的访问。
## 功能特点
- 基于FastMCP的服务器，采用装饰器模式
- 通过@mcp.tool()装饰器实现自动工具注册
- 类型安全的参数处理
- 全面的错误处理和日志记录
- 通过环境变量轻松配置
## 前置条件
- Python 3.10 或更高版本
- pip 包管理器
## 安装
1. 安装依赖：
```bash
pip install -r requirements.txt
```
2. 配置环境变量：
```bash
export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# 替代身份验证选项（仅使用一个）：
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"
```
## 运行MCP服务器
### STDIO模式（默认）
服务器默认在STDIO模式下运行，非常适合与Cursor等AI助手直接集成：
```bash
python main.py
```
### Cursor/Claude桌面配置
将以下内容添加到MCP配置文件（例如 `~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.json`）：
```json
{
"mcpServers": {
"instagram-mcp-server": {
"command": "python",
"args": ["/path/to/your/project/main.py"],
"env": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token"
}
}
}
}
```
## 环境变量
### 必需
- `API_BASE_URL`：API端点的基准URL
### 身份验证（使用以下之一）
- `BEARER_TOKEN`：OAuth2/Bearer身份验证的Bearer令牌
- `API_KEY`：API密钥身份验证的API密钥
- `BASIC_AUTH`：基本身份验证凭证（base64编码）
**注意**：除非API明确不需要身份验证，否则应提供至少一个身份验证变量。
## 开发
使用自动重载进行开发：
```bash
# 安装开发依赖
pip install -r requirements.txt
# 使用Python运行
python main.py
```
## 项目结构
```
.
├── main.py # FastMCP服务器的入口点
├── config.py # 配置管理
├── models.py # Pydantic数据模型
├── tools/ # 按类别组织的自动生成工具
│ ├── __init__.py
│ └── [category]/ # 按API端点类别分组的工具
│ ├── __init__.py
│ └── *.py # 单个工具实现
├── requirements.txt # Python依赖
└── README.md # 本文件
```
## 工作原理
该MCP服务器使用具有基于装饰器的架构的FastMCP构建：
1. **FastMCP服务器**：在`main.py`中创建MCP服务器实例
2. **工具装饰器**：每个工具都使用`@mcp.tool()`进行自动注册
3. **自动导入**：工具在导入其模块时自动注册
4. **类型安全**：使用Python类型提示进行参数验证
5. **错误处理**：具有JSON错误响应的全面错误处理
### 示例工具
```python
from main import mcp
@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
"""
从API获取用户。
参数：
search: 用于过滤用户的搜索查询
page: 用于分页的页码
返回：
包含用户数据的JSON字符串
"""
# 工具实现...
return json.dumps(result, indent=2)
```
## 身份验证方法
服务器支持多种身份验证方法：
### Bearer令牌（OAuth2）
```bash
export BEARER_TOKEN="your-bearer-token"
```
### API密钥
```bash
export API_KEY="your-api-key"
```
### 基本身份验证
```bash
export BASIC_AUTH="base64-encoded-credentials"
```
## 日志记录
服务器包含到stderr的综合日志记录：
- INFO级别：常规操作，工具注册
- WARNING级别：跳过的操作，缺少的参数
- ERROR级别：API错误，请求失败
在MCP客户端的控制台或stderr输出中查看日志。
## 故障排除
### “缺少必需参数”错误
- 检查是否提供了所有必需的参数
- 验证参数名称是否与工具定义匹配
### 身份验证错误
- 确保设置了正确的身份验证环境变量
- 验证您的凭证是否有效且未过期
- 检查API_BASE_URL是否正确
### 导入错误
- 运行`pip install -r requirements.txt`以确保安装了所有依赖
- 检查您是否正在使用Python 3.10或更高版本
### 工具未找到
- 验证工具名称是否与MCP客户端中显示的名称匹配
- 检查工具目录结构
- 确保所有`__init__.py`文件均存在
## 生成的工具
该服务器从OpenAPI规范自动生成。每个API端点都作为MCP工具公开，具有：
- 自动参数提取和验证
- 类型安全的参数处理
- 全面的错误处理
- JSON响应格式化
使用MCP客户端的工具列表功能查看所有可用的工具。
## 贡献
这是生成的MCP服务器。要修改工具行为：
1. 编辑`tools/[category]/[tool_name].py`中的工具实现
2. 保留`@mcp.tool()`装饰器进行注册
3. 保留函数签名进行参数验证
4. 通过在本地运行服务器来测试更改
## 许可证
此生成的MCP服务器遵循与生成器工具相同的许可证。
