A Model Context Protocol (MCP) server interface to Catalysis Hub's GraphQL API, enabling programmatic access to catalysis research data through flexible GraphQL queries.
- Direct GraphQL Access: Execute any valid GraphQL query against Catalysis Hub's API
- Comprehensive Data Access:
- Catalytic reactions (equations, conditions, catalysts)
- Material systems (structures, properties, descriptors)
- Research publications (titles, DOIs, authors)
- Surface reaction data (adsorption energies, binding sites)
- MCP Standard Compliance: Implements the Model Context Protocol for AI-agent interoperability
- Flexible Query Support: Execute complex queries with variables parameterization
- Error Handling: Robust error reporting for API connectivity and query execution
This project is available under the MIT License with an Academic Citation Requirement. This means you can freely use, modify, and distribute the code, but any academic or scientific publication that uses this software must provide appropriate attribution.
If you use this software in a research project that leads to a publication, presentation, or report, you must cite this work according to the format provided in CITATION.md.
Commercial and non-academic use follows the standard MIT License terms without the citation requirement.
By using this software, you agree to these terms. See LICENSE.md for the complete license text.
- Server Configuration (matches
claude_desktop_config.json
):{ "command": "/Users/quentincody/.env/bin/python3", "args": ["/Users/quentincody/catalysishub-mcp-server/catalysishub_mcp_server.py"], "options": { "cwd": "/Users/quentincody/catalysishub-mcp-server" } }
- Core Dependency:
httpx
for asynchronous HTTP requests - Transport: Standard input/output communication following MCP specifications
-
Clone the repository:
git clone <repository_url> cd catalysishub-mcp-server
-
Install dependencies:
pip install -r requirements.txt
-
Verify installation:
python3 catalysishub_mcp_server.py --version # Should output: catalysishub-mcp-server 0.1.0
from mcp.client import MCPClient
async with MCPClient("catalysishub") as hub:
result = await hub.catalysishub_graphql(
query="""{
reactions(first: 5) {
edges {
node {
id
Equation
Temperature
}
}
}
}"""
)
print(json.loads(result))
variables = {
"materialId": "mp-1234",
"firstResults": 5
}
response = await hub.catalysishub_graphql(
query="""query GetMaterial($materialId: String!, $firstResults: Int!) {
systems(uniqueId: $materialId) {
edges {
node {
energy
Cifdata
relatedReactions(first: $firstResults) {
edges {
node {
id
Equation
}
}
}
}
}
}
}""",
variables=variables
)
-
Use GraphQL Fragments:
fragment ReactionDetails on Reaction { id Equation ActivationEnergy Catalyst { formula surface } } query { reactions(first: 10) { edges { node { ...ReactionDetails } } } }
-
Batch Related Queries:
query BatchQuery { reactions: reactions(first: 5) { edges { node { id Equation } } } materials: systems(first: 5) { edges { node { formula energy } } } }
Successful responses follow this structure:
{
"data": { /* Query results */ },
"extensions": {
"responseMetadata": {
"requestDuration": 145,
"apiVersion": "2024-06"
}
}
}
Error responses include detailed diagnostics:
{
"errors": [{
"message": "Cannot query field 'invalidField' on type 'Reaction'",
"locations": [{"line": 5, "column": 21}],
"path": ["query", "reactions", "edges", "node", "invalidField"]
}]
}
Common Issues:
HTTP Request Error
: Verify network connectivity toapi.catalysis-hub.org
JSON Decode Error
: Check query syntax using Catalysis Hub's GraphQL PlaygroundTimeout Errors
: Addtimeout
parameter to complex queries
This project builds on the Model Context Protocol (MCP) framework and is designed to interface with the Catalysis Hub database, a comprehensive resource for catalysis research data.