# SpaceTraders MCP Server
A Model Context Protocol (MCP) server for interacting with the [SpaceTraders API](https://spacetraders.io/). 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](https://modelcontextprotocol.io) 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
1. Install uv if you don't have it:
```bash
pip install uv
```
2. Clone this repository:
```bash
git clone https://github.com/TheValverde/spacetraders-mcp.git
cd spacetraders-mcp
```
3. Install dependencies:
```bash
uv pip install -e .
```
4. Create a `.env` file in the project root and add your SpaceTraders API key:
```env
SPACETRADERS_API_KEY=your-api-key-here
```
### Using Docker (optional)
1. Build the Docker image:
```bash
docker build -t spacetraders-mcp .
```
2. Create a `.env` file 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
```bash
uv run src/main.py
```
### Using Docker
```bash
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):
```json
{
"mcpServers": {
"spacetraders": {
"transport": "sse",
"url": "http://localhost:8050/sse"
}
}
}
```
## Project Structure
- `src/main.py` — Main MCP server implementation and tool definitions
- `src/spacetraders_utils.py` — SpaceTraders API client and token management
- `src/utils.py` — Utility functions
- `agent_tokens.json` — Persistent agent tokens (auto-managed)
- `schemas/` — OpenAPI and reference JSON files for SpaceTraders API
- `public/` — Static assets
- `TODO.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.
