Tarkov MCP

🚀 Tarkov MCP Server

A Model Context Protocol (MCP) server that offers full access to Escape From Tarkov game data via the tarkov.dev GraphQL API.

🚀 Quick Start

This MCP server enables AI assistants to access in - depth information about Escape From Tarkov, such as items, traders, maps, quests, crafting recipes, etc. It serves as a comprehensive resource for players, developers, and AI applications in need of Tarkov game data.

✨ Features

Available Tools

The server provides 19 distinct 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:

   npm install
   

3. Configure environment variables (optional):

   TARKOV_API_ENDPOINT=https://api.tarkov.dev/graphql
   TARKOV_LANG=en
   

💻 Usage Examples

Basic Usage

Running the Server

npm start

The server will start and listen for MCP connections.

Advanced Usage

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, and 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, and crafting recipes.
• ammo: Returns ammunition data, including ballistic properties (damage, penetration, accuracy), armor damage and fragmentation, recoil and velocity modifiers, and tracer information.
• barter: Returns barter trade information, including required items and quantities, reward items and quantities, trader and level requirements, and task unlock requirements.
• traders: Returns trader information, including trader levels and requirements, available barters and cash offers, reputation levels and bonuses, and insurance and repair rates.
• tasks: Returns quest/task data, including objectives and requirements, rewards (items, experience, trader standing), prerequisites and unlock conditions, and 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, and key requirements.
• crafts: Returns crafting recipe data, including required materials and quantities, produced items, crafting station and level requirements, and crafting duration.
• hideout - stations: Returns hideout station information, including upgrade requirements (items, skills, trader levels), station bonuses and effects, crafting capabilities, and construction time and costs.

📚 Documentation

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, such as network connectivity issues, API rate limiting, invalid GraphQL queries, and missing or malformed data.

🔧 Technical Details

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 and Prettier for code formatting. Run formatting and linting:

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 for providing the comprehensive Tarkov API.
• Model Context Protocol 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.
• Open an issue on this repository.
• Join the community discussions.