Skip to content

Commit 621bcbd

Browse files
imaurerimaurer
committed
feat: Add Claude Desktop and MCP Inspector tutorials
* Adds a tutorial for configuring BioMCP with Claude Desktop * Includes steps for setting up Claude and using BioMCP tools * Adds a tutorial for testing BioMCP with MCP Inspector * Details how to use the Inspector to test BioMCP tools directly * Updates the main documentation index to reference tutorials * Includes troubleshooting tips and resources for Claude Desktop setup
1 parent 54bcca4 commit 621bcbd

5 files changed

Lines changed: 400 additions & 10 deletions

File tree

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ is in your PATH or provide a full path to it (e.g. /Users/name/.local/bin/uv).
9999
To verify your BioMCP MCP Server installation, use the MCP Inspector:
100100

101101
```bash
102-
npx @modelcontextprotocol/inspector uv run biomcp run
102+
npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run
103103
```
104104

105105
For more detailed instructions, see the [Installation Guide](installation.md).

‎docs/tutorials/claude-desktop.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# BioMCP with Claude Desktop: Step-by-Step Tutorial
2+
3+
This tutorial will guide you through setting up BioMCP as a Model Context
4+
Protocol (MCP) server for Claude Desktop, allowing Claude to access specialized
5+
biomedical data.
6+
7+
## Prerequisites
8+
9+
- Claude Desktop: [Download from Anthropic](https://claude.ai/desktop)
10+
- Python: 3.11 or newer
11+
- uv: [Installation](https://docs.astral.sh/uv/getting-started/installation/)
12+
13+
Verify the uv installation on the command line:
14+
15+
```bash
16+
uv --version
17+
```
18+
19+
Make sure it is installed globally for Claude to access. For instance,
20+
on MacOS, we recommend installing `uv` using Homebrew:
21+
22+
```bash
23+
% which uv
24+
/opt/homebrew/bin/uv
25+
```
26+
27+
## Configure Claude Desktop
28+
29+
Open Claude Desktop and access the Settings > Developer section.
30+
31+
Then click "Edit Config" which on MacOS opens up the folder containing this
32+
file:
33+
34+
```markdown
35+
claude_desktop_config.json
36+
```
37+
38+
Edit the file like this using your favorite text editor:
39+
40+
```json
41+
{
42+
"biomcp": {
43+
"command": "uv",
44+
"args": ["run", "--with", "biomcp-python", "biomcp", "run"]
45+
}
46+
}
47+
```
48+
49+
We also recommend using Sequential Thinking MCP, which can be added as well
50+
by making your whole file:
51+
52+
```json
53+
{
54+
"mcpServers": {
55+
"biomcp": {
56+
"command": "uv",
57+
"args": ["run", "--with", "biomcp-python", "biomcp", "run"]
58+
},
59+
"sequential-thinking": {
60+
"command": "npx",
61+
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
62+
}
63+
}
64+
}
65+
```
66+
67+
For more information about Sequential Thinking:
68+
[https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)
69+
70+
Save your JSON file and restart Claude Desktop.
71+
72+
## Using BioMCP with Claude
73+
74+
Upload loading, we recommend accessing the BioMCP "custom instructions" by
75+
clicking the "connector" icon below the chat that says "Attach from MCP".
76+
77+
In that dialog, select the biomcp instructions as an "integration" and the
78+
MCP resource will be added as text.
79+
80+
You should see at least 9 tools that can be accessed with BioMCP plus any
81+
other tools you have configured (10 total with sequential thinking, for
82+
instance).
83+
84+
Below are some example questions to try based on your use cases/research.
85+
86+
### Clinical Trials Queries
87+
88+
Try questions like:
89+
90+
- "Find Phase 3 clinical trials for lung cancer with immunotherapy"
91+
- "Are there any recruiting breast cancer trials near Boston?"
92+
- "What are the eligibility criteria for trial NCT04280705?"
93+
94+
### PubMed Articles Queries
95+
96+
Try questions like:
97+
98+
- "Summarize recent research on EGFR mutations in lung cancer"
99+
- "Find articles about the relationship between BRAF mutations and melanoma"
100+
- "Get the abstract of PubMed article 21717063"
101+
102+
### Genetic Variants Queries
103+
104+
Try questions like:
105+
106+
- "What's the clinical significance of the BRAF V600E mutation?"
107+
- "Find pathogenic variants in the TP53 gene"
108+
- "Explain the difference between Class I and Class III BRAF mutations"
109+
-
110+
111+
### Combination Queries
112+
113+
Claude can combine multiple BioMCP tools in a single query:
114+
115+
```
116+
I'm researching KRAS G12C mutations in lung cancer. Can you find:
117+
1. The key characteristics of this mutation
118+
2. Recent clinical trials targeting it
119+
3. Significant research papers from the last 2 years
120+
```
121+
122+
Claude can help with complex biomedical research workflows:
123+
124+
```
125+
I'm studying treatment resistance in ALK-positive lung cancer. Can you help me:
126+
1. Identify the main ALK fusion variants
127+
2. Find current clinical trials testing next-generation ALK inhibitors
128+
3. Summarize recent literature on resistance mechanisms
129+
```
130+
131+
## Troubleshooting
132+
133+
### Common Issues
134+
135+
1. **"SPAWN ENOENT" Error**:
136+
137+
- Make sure `uv` is in your PATH
138+
- Try using the full path to `uv` in the configuration
139+
140+
2. **Claude doesn't use BioMCP**:
141+
142+
- Verify you've correctly configured the MCP server
143+
- Try restarting Claude Desktop
144+
- Check if your query is specific enough to trigger BioMCP usage
145+
146+
3. **No results returned**:
147+
- Your query may be too specific or use terms not in the databases
148+
- Try reformulating with more standard medical terminology
149+
150+
### Getting Help
151+
152+
- Check the [BioMCP documentation](https://biomcp.org/troubleshooting/macos/)
153+
for more troubleshooting tips
154+
- Visit the GitHub repository
155+
at [genomoncology/biomcp](https://github.com/genomoncology/biomcp) for issues
156+
and updates
157+
158+
## Resources
159+
160+
- [BioMCP Documentation](https://biomcp.org)
161+
- [Claude Desktop Documentation](https://docs.anthropic.com/claude/docs/claude-desktop)
162+
- [Model Context Protocol (MCP) Guide](https://docs.anthropic.com/claude/docs/model-context-protocol)

‎docs/tutorials/mcp-inspector.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Testing BioMCP with MCP Inspector: Step-by-Step Tutorial
2+
3+
This tutorial guides you through using the MCP Inspector to test and debug
4+
BioMCP integration. The MCP Inspector provides a user-friendly interface to
5+
interact with BioMCP directly, without needing to integrate with an AI
6+
assistant first.
7+
8+
## What is the MCP Inspector?
9+
10+
The MCP Inspector is a tool developed by Anthropic that allows you to:
11+
12+
- Test MCP servers like BioMCP directly
13+
- Browse available tools and their parameters
14+
- Send test requests and view responses
15+
- Debug MCP server integrations
16+
17+
## Step 1: Start MCP Inspector
18+
19+
To run biomcp inside the MCP inspector, use the following command:
20+
21+
```bash
22+
npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run
23+
```
24+
25+
This will launch the inspector interface (usually at http://127.0.0.1:6274).
26+
27+
## Step 2: Connect
28+
29+
Press the "Connect" button to establish a connection to the MCP server.
30+
31+
## Step 3: List Tools
32+
33+
The Inspector should display the available BioMCP tools:
34+
35+
- `article_searcher`
36+
- `article_details`
37+
- `trial_searcher`
38+
- `trial_protocol`
39+
- `trial_locations`
40+
- `trial_outcomes`
41+
- `trial_references`
42+
- `variant_searcher`
43+
- `variant_details`
44+
45+
Click on any tool to see its description and input parameters.
46+
47+
## Step 4: Test BioMCP Tools
48+
49+
Let's test each BioMCP tool with example inputs. For each test:
50+
51+
1. Select the tool from the list
52+
2. Copy and paste the corresponding JSON input
53+
3. Click "Call Tool" to send the request
54+
4. Review the response in the Output section
55+
56+
### Tool 1: article_searcher
57+
58+
**Input:**
59+
60+
```json
61+
{
62+
"genes": ["EGFR"],
63+
"diseases": ["NSCLC"],
64+
"variants": ["BRAF V600E"],
65+
"keywords": ["MEK Inhibitors"],
66+
"chemicals": ["Afatinib"]
67+
}
68+
```
69+
70+
**Example Output:**
71+
72+
```markdown
73+
# Record 1
74+
75+
Pmid: 33402199
76+
Pmcid: PMC7786519
77+
Title: MEK inhibitors for the treatment of non-small cell lung cancer
78+
Journal: J Hematol Oncol
79+
Date: 2021-01-05T00:00:00Z
80+
Doi: 10.1186/s13045-020-01025-7
81+
Abstract:
82+
BRAF and KRAS are two key oncogenes in the RAS/RAF/MEK/MAPK signaling
83+
pathway. Concomitant mutations in both KRAS and BRAF genes have been
84+
```
85+
86+
### Tool 2: article_details
87+
88+
**Input:**
89+
90+
```text
91+
21717063
92+
```
93+
94+
**Example Output:**
95+
96+
Same as `article_search` first record but with Full Text after the abstract:
97+
98+
```markdown
99+
Full Text:
100+
Introduction
101+
Lung cancer is the most common cause of cancer-related death worldwide,...
102+
```
103+
104+
### Tool 3: trial_searcher
105+
106+
**Input:**
107+
108+
```json
109+
{
110+
"conditions": ["Lung Cancer"],
111+
"interventions": ["Pembrolizumab"],
112+
"recruiting_status": "OPEN",
113+
"phase": "PHASE3"
114+
}
115+
```
116+
117+
**Example Output:**
118+
119+
```markdown
120+
# Record 1
121+
122+
Nct Number: NCT06847334
123+
Study Title:
124+
A Study to Compare the Efficacy, Safety, Immunogenicity, and
125+
Pharmacokinetic Profile of HLX17 Vs. Keytruda® in the First-Line
126+
Treatment of Advanced Non-squamous Non-small Cell Lung Cancer
127+
Study Url: https://clinicaltrials.gov/study/NCT06847334
128+
Study Status: NOT_YET_RECRUITING
129+
Brief Summary:
130+
This is a multicentre, randomized, double-blind, parallel-controlled
131+
integrated phase I/III clinical study to evaluate the similarity in
132+
efficacy, safety, PK profile, and immunogenicity of HLX17 vs. Keytruda®(
133+
US- and EU-sourced) in the first-line treatment of advanced non-squamous
134+
...
135+
```
136+
137+
### Tool 4: trial_protocol
138+
139+
### Tool 5: trial_locations
140+
141+
### Tool 6: trial_outcomes
142+
143+
### Tool 7: trial_references
144+
145+
All trial "detail" tools work the same way by specifying the NCT ID.
146+
147+
**Input:**
148+
149+
```text
150+
NCT04280705
151+
```
152+
153+
**Example Output:**
154+
155+
```markdown
156+
Url: https://clinicaltrials.gov/study/NCT04280705
157+
158+
# Protocol Section
159+
160+
## Identification Module
161+
162+
Nct Id: NCT04280705
163+
Brief Title: Adaptive COVID-19 Treatment Trial (ACTT)
164+
Official Title:
165+
A Multicenter, Adaptive, Randomized Blinded Controlled Trial of the
166+
Safety and Efficacy of Investigational Therapeutics for the Treatment of
167+
COVID-19 in Hospitalized Adults
168+
...
169+
```
170+
171+
### Tool 8: variant_searcher
172+
173+
**Input:**
174+
175+
```json
176+
{
177+
"gene": "BRAF",
178+
"hgvsp": "p.V600E",
179+
"size": 5
180+
}
181+
```
182+
183+
### Tool 9: variant_details
184+
185+
**Input:**
186+
187+
```text
188+
rs113488022
189+
```
190+
191+
or
192+
193+
```text
194+
chr7:g.140453136A>T
195+
```
196+
197+
### Testing Location-Based Search
198+
199+
**Tool**: `trial_searcher`
200+
**Input**:
201+
202+
```json
203+
{
204+
"conditions": ["Breast Cancer"],
205+
"recruiting_status": "OPEN",
206+
"lat": 42.3601,
207+
"long": -71.0589,
208+
"distance": 100
209+
}
210+
```
211+
212+
### Testing Variant Filtering
213+
214+
**Tool**: `variant_searcher`
215+
**Input**:
216+
217+
```json
218+
{
219+
"gene": "TP53",
220+
"significance": "pathogenic",
221+
"max_frequency": 0.01,
222+
"cadd": 20,
223+
"size": 10
224+
}
225+
```

0 commit comments

Comments
 (0)