yandex-wiki-mcp 0.1.1
MCP server for Yandex Wiki - provides access to corporate wiki pages via Model Context Protocol
License: MIT
Requires Python: >=3.11
Keywords: ai, claude, mcp, wiki, yandex

# Yandex Wiki MCP Server

[![PyPI version](https://badge.fury.io/py/yandex-wiki-mcp.svg)](https://pypi.org/project/yandex-wiki-mcp/)

MCP (Model Context Protocol) server for accessing Yandex Wiki pages from AI assistants like Claude.

## Features

- **page_get**: Fetch wiki page content and metadata by slug (path)
- **page_get_url**: Get web URL for a wiki page

## Installation

### Using uvx (recommended)

```bash
uvx yandex-wiki-mcp
```

### Using pip

```bash
pip install yandex-wiki-mcp
yandex-wiki-mcp
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WIKI_TOKEN` | Yes* | Yandex OAuth token for Wiki API |
| `TRACKER_TOKEN` | Yes* | Fallback: Yandex OAuth token (same as Tracker) |
| `WIKI_ORG_ID` | Yes* | Yandex organization ID |
| `TRACKER_ORG_ID` | Yes* | Fallback: Yandex organization ID |
| `WIKI_API_BASE_URL` | No | API base URL (default: `https://api.wiki.yandex.net/v1`) |
| `WIKI_WEB_BASE_URL` | No | Web interface URL (default: `https://wiki.yandex.ru`) |
| `REQUEST_TIMEOUT` | No | Request timeout in seconds (default: 30) |

*At least one token (`WIKI_TOKEN` or `TRACKER_TOKEN`) and one org ID (`WIKI_ORG_ID` or `TRACKER_ORG_ID`) must be set.

### Token Fallback

The server supports token fallback for environments where Tracker is already configured:

1. `WIKI_TOKEN` (highest priority)
2. `TRACKER_TOKEN` (fallback)

Same applies for organization ID:

1. `WIKI_ORG_ID` (highest priority)
2. `TRACKER_ORG_ID` (fallback)

### Getting an OAuth Token

1. Go to https://oauth.yandex.ru/
2. Click "Create app"
3. Select "For API access or debugging"
4. Enter app name and contact email
5. Grant necessary permissions for Wiki access
6. Copy the generated token

### Finding Organization ID

1. Open Yandex Tracker
2. Go to Admin settings -> Organizations
3. Copy the ID field value

## MCP Configuration

Add to your Claude MCP configuration (`~/.claude/mcp.json` or project's `.mcp.json`):

```json
{
  "mcpServers": {
    "yandex-wiki": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yandex-wiki-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "${TRACKER_TOKEN}",
        "TRACKER_ORG_ID": "your-org-id"
      }
    }
  }
}
```

## Usage Examples

### Fetch a page

```
Use page_get with slug "teams/dev/onboarding"
```

### Get page URL

```
Use page_get_url with slug "teams/dev/docs"
```

## API Limitations

### No Automatic Redirects

Yandex Wiki API does not follow redirects automatically. If a page has been moved and redirects to another location, the API will return a 404 error.

To handle this:
1. Check the exact page path in the Yandex Wiki web interface
2. Use the final destination path, not the redirect source

### Permission-based Access

API requests carry the same access permissions as the authenticated user. If the user cannot access a page in the web interface, the API will also deny access.

## Development

### Project Structure

```
yandex-wiki-mcp/
├── mcp_wiki/
│   ├── __init__.py
│   ├── __main__.py
│   ├── settings.py
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── server.py
│   │   ├── context.py
│   │   └── errors.py
│   └── wiki/
│       ├── __init__.py
│       ├── client.py
│       └── proto/types/pages.py
├── pyproject.toml
└── README.md
```

### Running locally

```bash
git clone https://github.com/sashagrande/yandex-wiki-mcp.git
cd yandex-wiki-mcp
export TRACKER_TOKEN="your-token"
export TRACKER_ORG_ID="your-org-id"
uv run yandex-wiki-mcp
```

### Code style

The project uses:
- `ruff` for linting and formatting
- `mypy` for type checking
- `structlog` for logging

## License

MIT