https://github.com/openbankproject/obp-mcp
An MCP Server for the OBP API
https://github.com/openbankproject/obp-mcp
Last synced: 18 days ago
JSON representation
An MCP Server for the OBP API
- Host: GitHub
- URL: https://github.com/openbankproject/obp-mcp
- Owner: OpenBankProject
- License: agpl-3.0
- Created: 2025-11-17T13:46:13.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T07:07:42.000Z (21 days ago)
- Last Synced: 2026-05-22T15:25:36.481Z (21 days ago)
- Language: Python
- Size: 1.17 MB
- Stars: 3
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# OBP-MCP
MCP Server for the Open Bank Project API - enables AI assistants to interact with 600+ OBP API endpoints via tag-based routing and glossary access.
## Quick Start
### Install uv
**MacOS/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Setup
1. Create `.env` file:
```bash
OBP_BASE_URL=https://apisandbox.openbankproject.com
OBP_VERSION_TO_CALL=v7.0.0
API_VERSION_OF_INTEREST=v7.0.0
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=9100
```
2. Generate indexes:
```bash
uv run python scripts/generate_endpoint_index.py
uv run python scripts/generate_glossary_index.py
```
3. Run server:
```bash
uv sync
./run_server.sh
```
Server starts at `http://0.0.0.0:9100`
## Authentication
OBP-MCP supports three authentication modes:
| Mode | Use Case | `AUTH_PROVIDER` |
| --------------- | ---------------------------------------------- | --------------- |
| **bearer-only** | Internal agents (Opey), microservices | `bearer-only` |
| **obp-oidc** | External MCP clients (VS Code, Claude Desktop) | `obp-oidc` |
| **keycloak** | External MCP clients with Keycloak | `keycloak` |
### For Opey (Internal Agent)
Use `bearer-only` authentication. This mode:
- **Does NOT** expose OAuth discovery endpoints
- Simply validates JWT tokens against OBP-OIDC's JWKS
- Is designed for architectures where OAuth is handled externally (e.g., by a frontend portal)
```bash
# .env
ENABLE_OAUTH="true"
AUTH_PROVIDER=bearer-only
OBP_OIDC_ISSUER_URL=http://localhost:9000/obp-oidc
```
Your agent passes the user's access token with each MCP request:
```
Authorization: Bearer
```
### For External MCP Clients (VS Code, Claude Desktop, MCP Inspector)
Use `obp-oidc` or `keycloak` authentication. These modes expose the full OAuth 2.1 discovery flow, allowing MCP clients to:
- Discover authorization endpoints via `/.well-known/oauth-protected-resource`
- Perform Dynamic Client Registration (RFC 7591)
- Complete the OAuth authorization code flow with PKCE
```bash
# .env
ENABLE_OAUTH="true"
AUTH_PROVIDER=obp-oidc
OBP_OIDC_ISSUER_URL=http://localhost:9000/obp-oidc
BASE_URL=http://localhost:9100
```
### Disabling Authentication
For development or testing without authentication:
```bash
ENABLE_OAUTH="false"
```
for more information about auth and how to configure your OIDC providers see the [docs](docs/AUTH_SETUP.md).
## Testing with MCP Inspector
Run the server normally then start the inspector with:
```bash
npx @modelcontextprotocol/inspector \
```
You can then configure the connection to the server from there.
## Client Integration
### VS Code
Configure in the servers section of `~/.config/Code/User/mcp.json`:
```json
{
"servers": {
"obp-mcp": {
"url": "http://0.0.0.0:9100/mcp",
"type": "http"
}
}
}
```
### Zed
Configure in `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"obp-mcp": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:9100/mcp"]
}
}
}
```
### Claude (code)
Configure in ~/.claude.json. The relevant section is:
```json
"mcpServers": {
"obp-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://127.0.0.1:9100/mcp"
],
"env": {}
}
}
```
This is a global config that makes the obp-mcp server available to all projects. It connects to http://127.0.0.1:9100/mcp using mcp-remote.
## Available Tools
**Endpoint Tools:**
- `list_endpoints_by_tag` - Filter 600+ endpoints by category
- `get_endpoint_schema` - Fetch full OpenAPI schema
- `call_obp_api` - Execute API requests
**Glossary Tools:**
- `list_glossary_terms` - Search 800+ OBP terms
- `get_glossary_term` - Get full definitions
See [docs/HYBRID_ROUTING.md](docs/HYBRID_ROUTING.md) for details.
## Appendix 1 - Opey setup
To set up with opey, use the following setup:
```bash
# .env
ENABLE_OAUTH="true"
AUTH_PROVIDER=bearer-only
OBP_OIDC_ISSUER_URL=http://localhost:9000/obp-oidc
OBP_AUTHORIZATION_VIA="consent"
OBP_OPEY_CONSUMER_KEY=
```
> [!IMPORTANT] `OBP_AUTHORIZATION_VIA` must be set to `oauth` or `consent`. Any other value (including unset) causes the server to refuse to start — unauthenticated OBP-API access is not supported.
> [!NOTE] You will not be able to use the MCP server, set up in this way, with any other MCP clients, unless they are capable of creating valid consents on the fly.
In Opey's `mcp_servers.json` (inside the servers array):
```json
{
"name": "obp",
"url": "http://0.0.0.0:9100/mcp",
"transport": "streamable_http",
"forward_bearer_token": true
}
```
## License
AGPLv3