spendcastai/spendcast-mcp

Spendcast MCP Server

A Model Context Protocol (MCP) server that provides access to Spendcast GraphDB through SPARQL queries. This server enables AI assistants like Claude Desktop to interact with your GraphDB knowledge base directly through natural language conversations.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources, APIs, and tools. It enables AI models to:

• Query databases and knowledge bases
• Execute code and scripts
• Access real-time information
• Interact with external services

Features

• SPARQL Query Execution: Execute SPARQL queries against GraphDB
• Secure Authentication: Basic authentication with username/password
• Error Handling: Comprehensive error handling for network and HTTP issues
• Async Support: Built with async/await for high performance
• Easy Integration: Simple setup for Claude Desktop and other MCP clients

Prerequisites

• Python 3.10 or higher
• Access to a GraphDB instance
• GraphDB credentials (username/password)

Installation

Install from source (recommended for development)

# Clone the repository
git clone <your-repo-url>
cd spendcast-mcp

# Install dependencies using uv (recommended)
uv sync

Configuration

Set the following environment variables:

export GRAPHDB_URL="http://your-graphdb-host:7200/repositories/your-repo"
export GRAPHDB_USER="your-username"
export GRAPHDB_PASSWORD="your-password"

Or create a .env file in your project directory:

GRAPHDB_URL=http://your-graphdb-host:7200/repositories/your-repo
GRAPHDB_USER=your-username
GRAPHDB_PASSWORD=your-password

Usage

Using with Claude Desktop

1. Install Claude Desktop from Anthropic's website

2. Configure MCP in Claude Desktop:

   • Open Claude Desktop
   • Go to Settings → Model Context Protocol
   • Click "Add Server"
   • Configure the server:
     • Name: Spendcast GraphDB
     • Command: spendcast-mcp
     • Working Directory: Leave empty (or specify if needed)
     • Environment Variables: Add your GraphDB credentials

3. Start a conversation and ask Claude to query your GraphDB:

   "Can you query the GraphDB to find all entities related to project spending?"
   "What are the top 10 spending categories in our database?"
   "Show me all transactions from last month"
   

Using with Other MCP Clients

This server is compatible with any MCP client. Common alternatives include:

• Cursor: AI-powered code editor with MCP support
• Continue: AI pair programming tool
• Custom MCP clients: Build your own using the MCP specification

Available Tools

get_schema_help

Provides immediate access to complete schema information and working examples. This is the recommended tool to use before writing SPARQL queries as it returns all the content directly.

Returns: Dictionary containing complete schema content and examples

get_schema_content

Reads and returns the actual content of specific schema resources. Use this if you need to access individual resources separately.

Parameters:

• resource_name (string): Which resource to read. Options: "schema_summary", "example_queries", "ontology"

Returns: Dictionary containing the resource content and metadata

Note: The ontology resource automatically falls back to the online version at https://static.rwpz.net/spendcast/schema# if local files are not available.

execute_sparql

Executes SPARQL queries against your GraphDB instance.

Parameters:

• query (string): The SPARQL query to execute

Example usage:

SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

Working Examples: The server includes several working SPARQL examples for:

• Customer transaction analysis
• Account and payment card usage
• Spending patterns by category and merchant
• Payment card usage patterns

See the server documentation for complete working examples.

Returns: JSON results from GraphDB or error information

Development

Running Tests

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=src/spendcast_mcp --cov-report=term-missing

# Run specific test
uv run pytest tests/test_server.py::test_execute_sparql_success -v

Project Structure

spendcast-mcp/
├── src/spendcast_mcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server implementation
├── tests/
│   └── test_server.py     # Test suite
├── pyproject.toml         # Project configuration
└── README.md

Troubleshooting

Common Issues

1. "GRAPHDB_URL environment variable not set"

   • Ensure all required environment variables are set
   • Check your .env file if using one

2. Connection refused to GraphDB

   • Verify GraphDB is running and accessible
   • Check firewall settings and network connectivity
   • Ensure the repository name in the URL is correct

3. Authentication failed

   • Verify username and password are correct
   • Check if the user has access to the specified repository

4. MCP client can't connect

   • Ensure the server is running (spendcast-mcp)
   • Check that the command path in your MCP client configuration is correct
   • Verify no firewall is blocking the connection

Debug Mode

Enable debug logging by setting the log level:

import logging
logging.basicConfig(level=logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

🔒 License and Usage Restrictions

The code and data in this repository are provided by PostFinance AG solely for participation in the BernHackt 2025 (22.08.2025 - 24.08.2025).

• Use is permitted only during the event.
• Redistribution, retention after the event, or use for any other purpose is strictly prohibited.
• All rights remain with PostFinance AG.

See for full terms.

Support

For issues and questions:

• Check the troubleshooting section above
• Review the test suite for usage examples
• Open an issue on the project repository

Related Links

• Model Context Protocol (MCP) Specification
• Claude Desktop
• GraphDB Documentation
• SPARQL Query Language