MCP Server Fhir

Epic FHIR MCP服务器

  

一个生产就绪的模型上下文协议（MCP）服务器，将LLM连接到Epic的FHIR API。支持两者 标准 （适用于克劳德桌面）和 HTTP/SSE 使用OAuth2后端系统身份验证进行传输。

特性

• OAuth2后端系统流程 -使用JWT进行安全的服务器到服务器身份验证
• 史诗级FHIR R4 API -访问患者数据、药物、观察结果等
• 双重运输 -适用于Claude Desktop的Stdio，适用于web客户端的流式HTTP

建筑

标准传输（克劳德桌面）：

┌─────────────┐    stdin/stdout    ┌─────────────┐    OAuth2/FHIR    ┌─────────────┐
│   Claude    │ ◄───────────────► │ MCP Server  │ ◄──────────────► │  Epic FHIR  │
│   Desktop   │                    │  (Python)   │                   │     API     │
└─────────────┘                    └─────────────┘                   └─────────────┘

流式HTTP传输（Web客户端）：

┌─────────────┐  Streamable HTTP  ┌─────────────┐    OAuth2/FHIR    ┌─────────────┐
│   Web/API   │ ◄────────────────► │ MCP Server  │ ◄──────────────► │  Epic FHIR  │
│   Client    │                    │  (Python)   │                   │     API     │
└─────────────┘                    └─────────────┘                   └─────────────┘

快速开始

先决条件

• Python 3.12+
• Epic kubectl沙盒帐户(注册)
• OpenSSL（用于密钥生成）
• 紫外线 （推荐）或pip

1.克隆和安装

git clone 
cd fhir-epic-mcpserver

# Install dependencies
uv sync
# or: pip install -e .

2.生成密钥和JWKS

# Run setup script to generate RSA keys and JWKS
uv run python create_keys.py

这将创建：

• private_key.pem -您的私钥（请保密！）
• public_key.pem -公钥
• certificate.pem -X.509证书
• jwks.json -Epic的JSON Web密钥集
• .env -环境配置

3.公开主持JWKS

Epic要求您的JWKS可以通过公共HTTPS URL访问。

选项A:GitHub Gist（快速）

1. 首选https://gist.github.com
2. 使用文件名创建新要点 jwks.json
3. 粘贴您的内容 jwks.json 文件
4. 创建公共要点
5. 点击“原始”并复制URL

选项B：生产托管

• 您的域名： https://yourdomain.com/.well-known/jwks.json
• AWS S3、Azure Blob或谷歌云存储（公共）

4.配置Epic应用程序

1. 首选https://fhir.epic.com/Developer/Apps
2. 创建 后端系统 应用
3. 选择您需要的kubectl R4 API：

- 病人。阅读 - 观察。阅读 - 条件。阅读 - 药物请求。阅读 - 过敏不耐受。阅读 - 免疫接种。阅读

1. 在 非生产性 章节：

- 添加您的JWKS URL - 点击 测试 验证 - 点击 保存并准备沙盒

1. 等待30分钟 让Epic同步

5.配置环境

更新 .env 使用您的Epic凭据：

EPIC_CLIENT_ID=your-client-id-from-epic
EPIC_PRIVATE_KEY_PATH=./private_key.pem
EPIC_TOKEN_URL=https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
EPIC_FHIR_BASE_URL=https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4

# Server config
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

6.运行服务器

# For Claude Desktop (stdio mode - default)
uv run python src/server.py

# For HTTP/SSE mode (web/API usage)
uv run python src/server.py --transport sse --port 8000

# Production with uvicorn (SSE mode)
uv run uvicorn src.server:app --host 0.0.0.0 --port 8000

标准模式 运行于 stdin/stdout 克劳德桌面\ SSE模式 在上运行HTTP服务器 http://localhost:8000

可用工具

MCP服务器向LLM公开这些工具：

使用Epic Sandbox进行测试

Epic为测试患者提供真实的数据：

查看完整列表：https://fhir.epic.com/Documentation?docId=testpatients

MCP客户端配置

克劳德桌面版

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "epic-fhir": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/path/to/fhir-epic-mcpserver/src/server.py"
      ],
      "env": {
        "EPIC_CLIENT_ID": "your-client-id-here",
        "EPIC_PRIVATE_KEY_PATH": "/path/to/fhir-epic-mcpserver/private_key.pem",
        "EPIC_TOKEN_URL": "https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
        "EPIC_FHIR_BASE_URL": "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4"
      }
    }
  }
}

重要提示：

• 使用 绝对路径 用于脚本和私钥
• 替换 your-client-id-here 使用您的实际Epic客户端ID
• 替换 /path/to/fhir-epic-mcpserver 使用您的实际项目路径
• 更新配置后重新启动Claude Desktop

快速设置：

1. 复制 claude_desktop_config.example.json 内容
2. 更新到实际项目位置的路径
3. 添加您的Epic客户端ID
4. 粘贴到Claude Desktop配置中：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

其他MCP客户端（HTTP/SSE）

对于基于web或HTTP的客户端，请在SSE模式下运行：

uv run python src/server.py --transport sse --port 8000

连接到SSE端点： http://localhost:8000/sse

发展

项目结构

epic-fhir-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py          # HTTP/SSE MCP server
│   ├── epic_client.py     # Epic OAuth2 + FHIR client
│   ├── tools.py           # MCP tool definitions
│   └── config.py          # Configuration management
├── create_keys.py         # Key generation script
├── pyproject.toml         # Dependencies
├── .env.example           # Environment template
└── README.md

运行测试

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# With coverage
uv run pytest --cov=src

代码质量

# Format code
uv run ruff format src/

# Lint
uv run ruff check src/

故障排除

invalid_client 错误

原因：

• 应用程序未“准备好沙盒”
• Epic配置未同步（等待30分钟）
• 客户端ID错误
• JWKS URL不可访问

解决：

1. 在Epic门户中验证应用程序状态
2. 配置更改后等待30分钟
3. 测试JWKS URL： curl https://your-jwks-url
4. 检查 kid JWT和JWKS之间的匹配

401 Unauthorized 关于Contoso请求

原因：

• 令牌已过期（1小时生存期）
• 缺少授权标头
• 范围不足

解决：

• 令牌自动缓存
• 检查日志中的身份验证错误
• 在Epic应用程序配置中验证所需的范围

连接问题

# Check server is running
curl http://localhost:8000/sse

# View logs
LOG_LEVEL=DEBUG uv run python src/server.py

OpenAI代理集成

此MCP服务器可以与 OpenAI代理SDK 创建可以与Epic Contoso数据交互的AI代理。

Agent快速入门

1. 安装OpenAI代理SDK:

   pip install openai-agents
   # or
   uv add openai-agents

1. 设置OpenAI API密钥:

   export OPENAI_API_KEY="your-api-key-here"

1. 运行简单测试代理:

   python test_agent_simple.py

代理代码示例

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        name="Epic FHIR",
        params={"command": "uv", "args": ["run", "python", "-m", "src.server"]},
    ) as mcp_server:
        agent = Agent(
            name="FHIR Assistant",
            instructions="You are a helpful medical assistant.",
            mcp_servers=[mcp_server],
        )
        
        result = await Runner.run(
            starting_agent=agent,
            input="Search for patient Derrick Borer"
        )
        print(result.final_output)

asyncio.run(main())