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!

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)

pip install -e .

Option 2: Install with development dependencies

pip install -e ".[dev]"

Option 3: Using requirements.txt (legacy)

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

{
  "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

pytest tests/ -v

Running the Server

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:

export LOG_LEVEL=DEBUG

Contributing

We welcome contributions! Please see 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.