Tarkov MCP Server

# Tarkov MCP Server A Model Context Protocol (MCP) server that provides comprehensive access to Escape From Tarkov game data through the [tarkov.dev](https://tarkov.dev) GraphQL API. ## Overview This MCP server allows AI assistants to access detailed information about Escape From Tarkov, including items, traders, maps, quests, crafting recipes, and much more. It's designed to be a comprehensive resource for players, developers, and AI applications that need Tarkov game data. ## Features ### Available Tools The server provides 19 different tools to access various aspects of Tarkov data: #### Core Game Data - **`achievement`** - Returns all achievements from Escape From Tarkov - **`items`** - Returns comprehensive item data including stats, prices, and properties - **`ammo`** - Returns detailed ammunition information including ballistics - **`armor-materials`** - Returns armor material properties and durability data #### Trading & Economy - **`barter`** - Returns all barter trades available from traders - **`traders`** - Returns trader information, levels, and offers - **`flea-market`** - Returns flea market configuration and fees #### Crafting & Hideout - **`crafts`** - Returns all crafting recipes and requirements - **`hideout-stations`** - Returns hideout station information and upgrades #### Quests & Progression - **`tasks`** - Returns all quests/tasks with objectives and rewards - **`quest-items`** - Returns special quest-only items - **`skills`** - Returns player skills information - **`player-levels`** - Returns player level progression data - **`mastering`** - Returns weapon mastering requirements #### Maps & Locations - **`maps`** - Returns detailed map information including extracts, spawns, and loot - **`bosses`** - Returns boss information including health, equipment, and drops - **`loot-containers`** - Returns loot container locations and spawn chances - **`stationary-weapons`** - Returns stationary weapon information #### System Information - **`server-status`** - Returns current Tarkov server status and messages ## Installation 1. Clone this repository 2. Install dependencies: ```bash npm install ``` 3. Configure environment variables (optional): ```bash TARKOV_API_ENDPOINT=https://api.tarkov.dev/graphql TARKOV_LANG=en ``` ## Usage ### Running the Server ```bash npm start ``` The server will start and listen for MCP connections. ### Configuration The server can be configured through environment variables: - `TARKOV_API_ENDPOINT` - GraphQL API endpoint (default: https://api.tarkov.dev/graphql) - `TARKOV_LANG` - Language code for localized content (default: en) ### Tool Details #### achievement Returns achievement data including: - Achievement name and description - Completion percentages - Rarity information - Side requirements (PMC/SCAV) #### items Returns comprehensive item data including: - Basic properties (name, description, size, weight) - Market prices and trends - Item properties specific to type (weapons, armor, consumables, etc.) - Trading information (barters, cash offers) - Quest usage - Crafting recipes #### ammo Returns ammunition data including: - Ballistic properties (damage, penetration, accuracy) - Armor damage and fragmentation - Recoil and velocity modifiers - Tracer information #### barter Returns barter trade information including: - Required items and quantities - Reward items and quantities - Trader and level requirements - Task unlock requirements #### traders Returns trader information including: - Trader levels and requirements - Available barters and cash offers - Reputation levels and bonuses - Insurance and repair rates #### tasks Returns quest/task data including: - Objectives and requirements - Rewards (items, experience, trader standing) - Prerequisites and unlock conditions - Map-specific information #### maps Returns detailed map information including: - Spawn points and extracts - Loot container and loose loot locations - Boss spawn information - Hazards and special zones - Key requirements #### crafts Returns crafting recipe data including: - Required materials and quantities - Produced items - Crafting station and level requirements - Crafting duration #### hideout-stations Returns hideout station information including: - Upgrade requirements (items, skills, trader levels) - Station bonuses and effects - Crafting capabilities - Construction time and costs ## API Reference All tools return data in JSON format directly from the tarkov.dev GraphQL API. The data structure follows the GraphQL schema definitions. ### Error Handling The server handles various error conditions: - Network connectivity issues - API rate limiting - Invalid GraphQL queries - Missing or malformed data ## Development ### Project Structure ``` src/ ├── config/ # Configuration management ├── logger/ # Logging utilities ├── tools/ # MCP tool implementations │ └── items/ # Individual tool modules │ ├── achievements/ │ ├── ammo/ │ ├── barter/ │ └── ... └── server.js # Main MCP server ``` ### Adding New Tools 1. Create a new directory under `src/tools/items/` 2. Implement `loader.js` with GraphQL query 3. Implement `index.js` with tool definition 4. Add to `src/tools/items/index.js` exports ### Code Style The project uses: - ESLint for code linting - Prettier for code formatting Run formatting and linting: ```bash npm run format npm run lint ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Run tests and linting 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Acknowledgments - [tarkov.dev](https://tarkov.dev) for providing the comprehensive Tarkov API - [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification - The Escape From Tarkov community for data validation and feedback ## Support For issues and questions: - Check the [tarkov.dev API documentation](https://tarkov.dev/api) - Open an issue on this repository - Join the community discussions