# Tarkov MCP Server

A Model Context Protocol (MCP) server that provides access to Escape from Tarkov game data through the community-maintained Tarkov API.

> [!IMPORTANT]  
> I am not affiliated with the tarkov.dev project or API. I simply built this MCP server to interact with what they have built. If you appreciate their work, please consider donating to them [here](https://opencollective.com/tarkov-dev)!

## Features

### Item Tools

- **search_items** - Search for items by name or type (supports localization)
- **get_item_details** - Get detailed item information including prices, stats, and usage
- **get_item_prices** - Get current pricing information for items
- **compare_items** - Compare multiple items side by side
- **get_quest_items** - Get quest-specific items with their associated tasks

### Market Tools

- **get_flea_market_data** - Current flea market price data
- **get_barter_trades** - Available barter exchanges from traders
- **calculate_barter_profit** - Profit/loss analysis for barter trades
- **get_ammo_data** - Ammunition statistics and pricing
- **get_hideout_modules** - Hideout module information and requirements

### Map Tools

- **get_maps** - List all available maps
- **get_map_details** - Detailed map information including spawns and extracts
- **get_map_spawns** - Spawn locations and information for specific maps

### Trader Tools

- **get_traders** - List all traders
- **get_trader_details** - Detailed trader information
- **get_trader_items** - Items available from specific traders

### Quest Tools

- **get_quests** - List quests, optionally filtered by trader
- **get_quest_details** - Detailed quest information including objectives and rewards
- **search_quests** - Search quests by name or description

### Community Tools

- **get_goon_reports** - Get recent community-driven goon squad sighting reports

## Installation

### Prerequisites

- Python 3.8 or higher
- pip package manager

### Install Dependencies

You can install the dependencies in several ways:

First, clone the repository and navigate into the repository root directory.

**Option 1: Install as a package (recommended)**

```bash
pip install -e .
```

**Option 2: Install with development dependencies**

```bash
pip install -e ".[dev]"
```

**Option 3: Using requirements.txt (legacy)**

```bash
pip install -r requirements.txt
```

### Claude Desktop Setup

To use this MCP server with Claude Desktop, make sure you've followed the install instructions above.

Add the following configuration to your Claude Desktop config file:

**On macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**On Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tarkov": {
      "command": "python",
      "args": ["-m", "tarkov_mcp"],
      "cwd": "/path/to/tarkov-mcp"
    }
  }
}
```

Replace `/path/to/tarkov-mcp` with the actual path to this project directory.

After updating the config file, restart Claude Desktop for the changes to take effect.

## Development

### Running Tests

```bash
pytest tests/ -v
```

### Running the Server

```bash
python -m tarkov_mcp
```

## Configuration

The server can be configured using environment variables:

- `TARKOV_API_URL` - Tarkov API endpoint (default: https://api.tarkov.dev/graphql)
- `MAX_REQUESTS_PER_MINUTE` - Rate limit (default: 60)
- `REQUEST_TIMEOUT` - Request timeout in seconds (default: 30)

## Features

- **Multi-language Support**: Full localization support for 16 languages (English, Russian, German, French, Spanish, etc.)
- **Enhanced Item Data**: Comprehensive item properties including new weapon ballistics, armor materials, and medical effects
- **Community Integration**: Goon squad tracking and quest-specific item information
- **Modern API Compatibility**: Updated GraphQL queries using latest Tarkov API schema structure
- **Rate Limiting**: Built-in rate limiting to respect API limits (60 requests per minute by default)
- **Error Handling**: Comprehensive error handling with detailed error messages
- **Async Support**: Fully asynchronous implementation for better performance
- **Comprehensive Testing**: Extensive test suite with pytest
- **Type Safety**: Full type hints throughout the codebase

## API Data Source

This server uses the community-maintained Tarkov API at https://api.tarkov.dev/graphql, which provides real-time data for Escape from Tarkov including:

- Item information and statistics
- Current market prices
- Trader information and barter trades
- Quest and task data
- Map and location information
- Ammunition data
- Hideout module requirements

## Troubleshooting

### Common Issues

1. **Rate Limiting**: If you encounter rate limit errors, the server will automatically retry with exponential backoff
2. **Network Issues**: Check your internet connection and ensure the Tarkov API is accessible
3. **Claude Desktop Integration**: Make sure the path in your config file is correct and Python is in your PATH

### Logging

The server includes comprehensive logging. To enable debug logging, set the environment variable:

```bash
export LOG_LEVEL=DEBUG
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

Quick start:

1. Fork the repository
2. Set up development environment: `pip install -e ".[dev]"`
3. Install pre-commit hooks: `pre-commit install`
4. Create a feature branch
5. Make your changes with tests
6. Run quality checks: `pre-commit run --all-files`
7. Submit a pull request

## License

GPL-3.0 License - see LICENSE file for details.