SpaceTraders MCP Server
A Model Context Protocol (MCP) server for interacting with the SpaceTraders API. This server exposes SpaceTraders API endpoints as MCP tools, allowing AI agents to manage agents, fleets, contracts, and trading operations in the SpaceTraders universe.
Overview
This project provides an MCP server that enables AI agents to:
- Register and manage SpaceTraders agents
- View and manage ships and fleets
- Accept, deliver, and fulfill contracts
- Trade resources and interact with markets
- Explore systems, waypoints, and shipyards
The implementation is based on the MCP standard, using the mcp Python package for server infrastructure.
Features
- Register new SpaceTraders agents
- View agent details and list agents
- List, view, accept, deliver, and fulfill contracts
- List ships, view ship details, purchase ships
- Navigate, dock, orbit, refuel, and extract resources with ships
- Transfer and sell cargo
- Scan systems, waypoints, and ships
- View markets and shipyards
- Chart waypoints and refine resources
See TODO.md for a detailed checklist of implemented and missing endpoints.
Prerequisites
- Python 3.12+
- SpaceTraders API key (from https://my.spacetraders.io)
- Docker (optional, for containerized deployment)
Installation
Using uv
-
Install uv if you don't have it:
pip install uv -
Clone this repository:
git clone https://github.com/TheValverde/spacetraders-mcp.git cd spacetraders-mcp -
Install dependencies:
uv pip install -e . -
Create a
.envfile in the project root and add your SpaceTraders API key:SPACETRADERS_API_KEY=your-api-key-here
Using Docker (optional)
-
Build the Docker image:
docker build -t spacetraders-mcp . -
Create a
.envfile in the project root and add your SpaceTraders API key.
Configuration
The following environment variable is required:
| Variable | Description |
|---|---|
SPACETRADERS_API_KEY | Your SpaceTraders account token |
Running the Server
Using uv
uv run src/main.py
Using Docker
docker run --env-file .env -p 8050:8050 spacetraders-mcp
MCP Integration
This server exposes SpaceTraders API endpoints as MCP tools. You can connect to it from any MCP-compatible client. Example configuration (update URL/port as needed):
{
"mcpServers": {
"spacetraders": {
"transport": "sse",
"url": "http://localhost:8050/sse"
}
}
}
Project Structure
src/main.py— Main MCP server implementation and tool definitionssrc/spacetraders_utils.py— SpaceTraders API client and token managementsrc/utils.py— Utility functionsagent_tokens.json— Persistent agent tokens (auto-managed)schemas/— OpenAPI and reference JSON files for SpaceTraders APIpublic/— Static assetsTODO.md— Endpoint implementation checklist
Schemas and Reference Data
The schemas/ directory contains large JSON files used for reference and development:
schemas/SpaceTraders.json— The official OpenAPI specification for the SpaceTraders API (v2). Used for endpoint reference and validation.schemas/SpaceTraderFullAPI.json— (Describe usage here if different, or remove if unused.)
These files are not required for running the server, but are useful for development, code generation, and documentation.
Development Status
See TODO.md for a list of implemented and missing endpoints. The core gameplay and trading endpoints are implemented; some advanced features are still TODO.
This project is licensed under the terms described in the LICENSE file included in this repository.