AI导哈

学术研究服务器

一个基于OpenAlex API的生产级模型上下文协议(MCP)服务器，提供学术研究工具，支持论文、作者、机构和研究主题的搜索与分析。

  • by gpetruzella
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gpetruzella/openalex-mcp-server

使用说明

OpenAlex MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，使用 OpenAlex API基于FastAPI构建，专为在Google Cloud Run上部署而设计。

特性

🔬 学术研究工具

  • 搜索工作 -搜索论文、文章和学术出版物
  • 搜索_作者 -使用h指数、引文查找研究人员及其个人资料
  • 获取工作详情 -获取特定论文的详细元数据
  • 搜索概念 -探索研究主题及其关系
  • 搜索_机构 -查找大学和研究机构
  • get_citations -分析引文网络（引用/被引作品）
  • 高级过滤器 -使用OpenAlex过滤器语法进行复杂的多条件搜索

🚀 MCP协议特性

  • 可流式HTTP传输 -基于HTTP/SSE的现代通信
  • JSON-RPC 2.0 -标准消息协议
  • 服务器发送的事件 -实时流媒体处理大量响应
  • 云就绪 -针对Google Cloud Run部署进行了优化

📊 OpenAlex礼貌访问

  • 自动速率限制（10个请求/秒）
  • 用于礼貌访问池的Mailto参数
  • 正确的User-Agent标头
  • 重试次数呈指数级回退

快速开始

地方发展

  1. 克隆和设置:
cd openalex-mcp-server
cp .env.example .env
# Edit .env and set your MAILTO_EMAIL
  1. 安装依赖项:
pip install -r requirements.txt
  1. 运行服务器:
python server.py
# Or with uvicorn:
uvicorn server:app --reload --port 8080
  1. 测试端点:
curl http://localhost:8080/health

Docker本地测试

docker build -t openalex-mcp-server .
docker run -p 8080:8080 -e MAILTO_EMAIL=your-email@williamscollege.edu openalex-mcp-server

谷歌云运行部署

先决条件

  • 谷歌云SDK 安装
  • 启用云运行API的GCP项目
  • 本地安装Docker

部署步骤

  1. 使用Google Cloud进行身份验证:
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
  1. 构建和推送容器:
# Configure Docker for Google Container Registry
gcloud auth configure-docker

# Build the image
docker build -t gcr.io/YOUR_PROJECT_ID/openalex-mcp-server .

# Push to Container Registry
docker push gcr.io/YOUR_PROJECT_ID/openalex-mcp-server
  1. 部署到云端运行:
gcloud run deploy openalex-mcp-server \
  --image gcr.io/YOUR_PROJECT_ID/openalex-mcp-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars MAILTO_EMAIL=your-email@williamscollege.edu \
  --memory 512Mi \
  --cpu 1 \
  --max-instances 10
  1. 获取您的服务URL:
gcloud run services describe openalex-mcp-server --platform managed --region us-central1 --format 'value(status.url)'

备选方案：一个命令部署

gcloud run deploy openalex-mcp-server \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars MAILTO_EMAIL=your-email@williamscollege.edu

MCP客户端配置

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "openalex": {
      "transport": "streamable-http",
      "url": "https://YOUR-SERVICE-URL.run.app/mcp",
      "description": "OpenAlex academic research API"
    }
  }
}

配置文件位置:

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

其他MCP客户端

服务器通过HTTP/SSE实现了标准的MCP，因此它可以与任何兼容的客户端一起工作：

import httpx
import json

# Initialize request
init_message = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2025-03-26",
        "clientInfo": {
            "name": "my-client",
            "version": "1.0.0"
        }
    }
}

response = httpx.post(
    "https://YOUR-SERVICE-URL.run.app/mcp",
    json=init_message,
    headers={"Content-Type": "application/json"}
)

print(response.json())

用法示例

搜索论文

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_works",
    "arguments": {
      "query": "machine learning climate change",
      "publication_year": "2020-2024",
      "open_access": true,
      "limit": 10
    }
  }
}

寻找研究人员

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_authors",
    "arguments": {
      "name": "Andrew Ng",
      "institution": "Stanford",
      "limit": 5
    }
  }
}

获取引文网络

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_citations",
    "arguments": {
      "work_id": "W2741809807",
      "direction": "citing",
      "limit": 50
    }
  }
}

高级过滤

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "advanced_filter",
    "arguments": {
      "entity_type": "works",
      "filters": {
        "publication_year": ">2020",
        "cited_by_count": ">100",
        "is_oa": true
      },
      "search": "artificial intelligence",
      "sort": "cited_by_count:desc",
      "limit": 25
    }
  }
}

API终点

POST/mcp

JSON-RPC消息的主MCP端点。支持JSON和SSE响应。

标头:

  • Content-Type: application/json （必填）
  • Accept: application/json （JSON响应）或 Accept: text/event-stream 上海证券交易所

GET/mcp

服务器发起的消息（保活、通知）的可选SSE端点。

标头:

  • Accept: text/event-stream （必填）

GET/健康

用于监视的健康检查端点。

响应: {"status": "healthy", "service": "openalex-mcp-server", "version": "1.0.0"}

得到/

服务信息和端点文档。

环境变量

变量 默认值 描述
PORT 8080 服务器端口（云运行自动设置）
MAILTO_EMAIL researcher@williamscollege.edu 必需 为了礼貌地进入游泳池
OPENALEX_BASE_URL https://api.openalex.org OpenAlex API端点
MAX_REQUESTS_PER_SECOND 10 API调用的速率限制
LOG_LEVEL INFO 记录冗长
ALLOWED_ORIGINS None CORS允许的来源（逗号分隔）

建筑

openalex-mcp-server/
├── server.py              # FastAPI app with HTTP/SSE transport
├── mcp_handler.py         # MCP protocol & JSON-RPC handling
├── config.py              # Environment configuration
├── tools/
│   ├── __init__.py
│   ├── search.py          # OpenAlex API tool implementations
│   ├── filters.py         # Filter utilities
│   └── utils.py           # Formatting helpers
├── Dockerfile             # Cloud Run deployment
├── requirements.txt       # Python dependencies
├── .env.example           # Environment template
├── claude_desktop_config.json  # Client config example
└── README.md

发展

添加新工具

  1. 在中实现工具功能 tools/search.py:
async def my_new_tool(param1: str, param2: int = 10) -> str:
    """Tool description."""
    # Implementation
    return json.dumps(result)
  1. 添加到 MCPHandler 在 mcp_handler.py:
self.tools = {
    # ... existing tools
    "my_new_tool": my_new_tool,
}
  1. 在中添加架构 _get_tool_schema():
schemas = {
    # ... existing schemas
    "my_new_tool": {
        "description": "Tool description",
        "inputSchema": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "..."},
                "param2": {"type": "integer", "default": 10}
            },
            "required": ["param1"]
        }
    }
}

运行测试

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest

监控云运行

# View logs
gcloud run services logs read openalex-mcp-server --region us-central1

# Check service status
gcloud run services describe openalex-mcp-server --region us-central1

安全考虑

当前配置（开发）

  • 无需认证
  • CORS允许所有来源
  • 适用于测试和内部使用

生产硬化

  1. 启用身份验证:
gcloud run deploy openalex-mcp-server \
  --no-allow-unauthenticated
  1. 设置允许的来源 在 .env:
ALLOWED_ORIGINS=https://yourdomain.com,https://anotherdomain.com
  1. 使用云运行IAM 用于访问控制
  2. 启用云护甲 用于DDoS保护
  3. 设置VPC 用于专用网络

速率限制和礼貌访问

服务器实现了OpenAlex礼貌池最佳实践：

  • ✅ 10个请求/秒 速率限制（与不礼貌的6次请求/秒相比）
  • ✅ Mailto参数 在所有请求中
  • ✅ 用户代理标头 带有联系信息
  • ✅ 指数退避 对于错误
  • ✅ 响应缓存 （如适用）

始终设置 MAILTO_EMAIL 以获得更好的利率限制！

故障排除

问题：“不允许原产地”

解决方案：设置 ALLOWED_ORIGINS 环境变量或更新CORS中间件 server.py

问题：速率限制错误

解决方案：验证 MAILTO_EMAIL 已正确设置，以便礼貌地访问游泳池

问题：云运行超时

解决方案：增加部署超时时间：

gcloud run deploy openalex-mcp-server --timeout 300

问题：内存错误

解决方案：增加内存分配：

gcloud run deploy openalex-mcp-server --memory 1Gi

资源

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 添加新功能的测试
  4. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

  • OpenAlex API：support@openalex.org
  • 威廉姆斯学院：联系您的研究计算支持

专为威廉姆斯学院本科生研究人员而建 🎓

快乐的研究！ 🔬

相关 MCP