Skip to content
Back to search

wikipedia-mcp

A Model Context Protocol (MCP) server that retrieves information from Wikipedia to provide context to LLMs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rudra-ravi--wikipedia-mcp/badge.svg)](/listings/rudra-ravi--wikipedia-mcp)

HTML

<a href="/listings/rudra-ravi--wikipedia-mcp"><img src="/api/listings/rudra-ravi--wikipedia-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using pipx (Recommended for Claude Desktop)

The best way to install for Claude Desktop usage is with pipx, which installs the command globally:

# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install the Wikipedia MCP server
pipx install wikipedia-mcp

This ensures the `wikipedia-mcp` command is available in Claude Desktop's PATH.

Installing via Smithery

To install wikipedia-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@Rudra-ravi/wikipedia-mcp):

npx -y @smithery/cli install @Rudra-ravi/wikipedia-mcp --client claude

From PyPI (Alternative)

You can also install directly from PyPI:

pip install wikipedia-mcp

**Note**: If you use this method and encounter connection issues with Claude Desktop, you may need to use the full path to the command in your configuration. See the [Configuration](#configuration-for-claude-desktop) section for details.

Using a virtual environment

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install the package
pip install git+https://github.com/rudra-ravi/wikipedia-mcp.git

From source

# Clone the repository
git clone https://github.com/rudra-ravi/wikipedia-mcp.git
cd wikipedia-mcp

# Create a virtual environment
python3 -m venv wikipedia-mcp-env
source wikipedia-mcp-env/bin/activate

# Install in development mode
pip install -e .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 843 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Wikipedia MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@Rudra-ravi/wikipedia-mcp)](https://smithery.ai/server/@Rudra-ravi/wikipedia-mcp)
  3. [![Listed on Spark](https://img.shields.io/badge/Listed%20on-Spark-blue)](https://spark.entire.vc/assets/vb-wikipedia-mcp)
  4. [![AgentSeal MCP](https://agentseal.org/api/v1/mcp/wikipedia-mcp/badge)](https://agentseal.org/mcp/wikipedia-mcp)
  5. A Model Context Protocol (MCP) server that retrieves information from Wikipedia to provide context to Large Language Models (LLMs). This tool helps AI assistants access factual information from Wikipedia to ground their responses in reliable sources.
  6. <a href="https://glama.ai/mcp/servers/@Rudra-ravi/wikipedia-mcp">
  7. <img width="380" height="200" src="https://glama.ai/mcp/servers/@Rudra-ravi/wikipedia-mcp/badge" alt="Wikipedia Server MCP server" />
  8. </a>
  9. ![image](https://github.com/user-attachments/assets/e41382f7-111a-4105-97f3-7851c906843e)
  10. ## Overview
  11. The Wikipedia MCP server provides real-time access to Wikipedia information through a standardized Model Context Protocol interface. This allows LLMs to retrieve accurate and up-to-date information directly from Wikipedia to enhance their responses.
  12. ## Verified By
  13. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/rudra-ravi-wikipedia-mcp-badge.png)](https://mseep.ai/app/rudra-ravi-wikipedia-mcp)
  14. ## Features
  15. - **Search Wikipedia**: Find articles matching specific queries with enhanced diagnostics
  16. - **Retrieve Article Content**: Get full article text with all information
  17. - **Article Summaries**: Get concise summaries of articles
  18. - **Section Extraction**: Retrieve specific sections from articles
  19. - **Link Discovery**: Find links within articles to related topics
  20. - **Related Topics**: Discover topics related to a specific article
  21. - **Multi-language Support**: Access Wikipedia in different languages by specifying the `--language` or `-l` argument when running the server (e.g., `wikipedia-mcp --language ta` for Tamil).
  22. - **Country/Locale Support**: Use intuitive country codes like `--country US`, `--country China`, or `--country TW` instead of language codes. Automatically maps to appropriate Wikipedia language variants.
  23. - **Language Variant Support**: Support for language variants such as Chinese traditional/simplified (e.g., `zh-hans` for Simplified Chinese, `zh-tw` for Traditional Chinese), Serbian scripts (`sr-latn`, `sr-cyrl`), and other regional variants.
  24. - **Optional caching**: Cache API responses for improved performance using --enable-cache
  25. - **Modern MCP Transport Support**: Supports `stdio`, `http`, and `streamable-http` (with legacy `sse` compatibility).
  26. - **Optional MCP Transport Auth**: Secure network transports with `--auth-mode static` or `--auth-mode jwt`.
  27. - **Google ADK Compatibility**: Fully compatible with Google ADK agents and other AI frameworks that use strict function calling schemas
  28. ## Installation
  29. ### Using pipx (Recommended for Claude Desktop)
  30. The best way to install for Claude Desktop usage is with pipx, which installs the command globally:
  31. ```bash
  32. # Install pipx if you don't have it
  33. pip install pipx
  34. pipx ensurepath
  35. # Install the Wikipedia MCP server
  36. pipx install wikipedia-mcp
  37. ```
  38. This ensures the `wikipedia-mcp` command is available in Claude Desktop's PATH.
  39. ### Installing via Smithery
  40. To install wikipedia-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@Rudra-ravi/wikipedia-mcp):
  41. ```bash
  42. npx -y @smithery/cli install @Rudra-ravi/wikipedia-mcp --client claude
  43. ```
  44. ### From PyPI (Alternative)
  45. You can also install directly from PyPI:
  46. ```bash
  47. pip install wikipedia-mcp
  48. ```
  49. **Note**: If you use this method and encounter connection issues with Claude Desktop, you may need to use the full path to the command in your configuration. See the [Configuration](#configuration-for-claude-desktop) section for details.
  50. ### Using a virtual environment
  51. ```bash
  52. # Create a virtual environment
  53. python3 -m venv venv
  54. # Activate the virtual environment
  55. source venv/bin/activate
  56. # Install the package
  57. pip install git+https://github.com/rudra-ravi/wikipedia-mcp.git
  58. ```
  59. ### From source
  60. ```bash
  61. # Clone the repository
  62. git clone https://github.com/rudra-ravi/wikipedia-mcp.git
  63. cd wikipedia-mcp
  64. # Create a virtual environment
  65. python3 -m venv wikipedia-mcp-env
  66. source wikipedia-mcp-env/bin/activate
  67. # Install in development mode
  68. pip install -e .
  69. ```
  70. ## Usage
  71. ### Running the server
  72. ```bash
  73. # If installed with pipx
  74. wikipedia-mcp
  75. # If installed in a virtual environment
  76. source venv/bin/activate
  77. wikipedia-mcp
  78. # Specify transport protocol (default: stdio)
  79. wikipedia-mcp --transport stdio # For Claude Desktop
  80. wikipedia-mcp --transport http --host 0.0.0.0 --port 8080 --path /mcp
  81. wikipedia-mcp --transport streamable-http --host 0.0.0.0 --port 8080 --path /mcp
  82. wikipedia-mcp --transport sse # Legacy compatibility transport
  83. # Specify language (default: en for English)
  84. wikipedia-mcp --language ja # Example for Japanese
  85. wikipedia-mcp --language zh-hans # Example for Simplified Chinese
  86. wikipedia-mcp --language zh-tw # Example for Traditional Chinese (Taiwan)
  87. wikipedia-mcp --language sr-latn # Example for Serbian Latin script
  88. # Specify country/locale (alternative to language codes)
  89. wikipedia-mcp --country US # English (United States)
  90. wikipedia-mcp --country China # Chinese Simplified
  91. wikipedia-mcp --country Taiwan # Chinese Traditional (Taiwan)
  92. wikipedia-mcp --country Japan # Japanese
  93. wikipedia-mcp --country Germany # German
  94. wikipedia-mcp --country france # French (case insensitive)
  95. # List all supported countries
  96. wikipedia-mcp --list-countries
  97. # Optional: Specify host/port/path for network transport (use 0.0.0.0 for containers)
  98. wikipedia-mcp --transport http --host 0.0.0.0 --port 8080 --path /mcp
  99. # Optional: Enable caching
  100. wikipedia-mcp --enable-cache
  101. # Optional: Use Personal Access Token to avoid rate limiting (403 errors)
  102. wikipedia-mcp --access-token your_wikipedia_token_here
  103. # Or set via environment variable
  104. export WIKIPEDIA_ACCESS_TOKEN=your_wikipedia_token_here
  105. wikipedia-mcp
  106. # Optional: Secure incoming MCP network requests with static bearer token
  107. wikipedia-mcp --transport http --auth-mode static --auth-token your_mcp_token --host 0.0.0.0 --port 8080
  108. # Optional: Secure incoming MCP network requests with JWT validation
  109. wikipedia-mcp --transport http --auth-mode jwt --auth-jwks-uri https://issuer/.well-known/jwks.json --auth-issuer https://issuer
  110. # Security note: prefer http/streamable-http + auth-mode for exposed network transport.
  111. # Combine options
  112. wikipedia-mcp --country Taiwan --enable-cache --access-token your_wikipedia_token --transport http --path /mcp --port 8080
  113. ### Docker/Kubernetes
  114. When running inside containers, bind the HTTP MCP server to all interfaces and map
  115. the container port to the host or service:
  116. ```bash
  117. # Build and run with Docker
  118. docker build -t wikipedia-mcp .
  119. docker run --rm -p 8080:8080 wikipedia-mcp --transport http --host 0.0.0.0 --port 8080 --path /mcp
  120. ```
  121. Kubernetes example (minimal):
  122. ```yaml
  123. apiVersion: apps/v1
  124. kind: Deployment
  125. metadata:
  126. name: wikipedia-mcp
  127. spec:
  128. replicas: 1
  129. selector:
  130. matchLabels:
  131. app: wikipedia-mcp
  132. template:
  133. metadata:
  134. labels:
  135. app: wikipedia-mcp
  136. spec:
  137. containers:
  138. - name: server
  139. image: your-repo/wikipedia-mcp:latest
  140. args: ["--transport", "http", "--host", "0.0.0.0", "--port", "8080", "--path", "/mcp"]
  141. ports:
  142. - containerPort: 8080
  143. ---
  144. apiVersion: v1
  145. kind: Service
  146. metadata:
  147. name: wikipedia-mcp
  148. spec:
  149. selector:
  150. app: wikipedia-mcp
  151. ports:
  152. - name: http
  153. port: 8080
  154. targetPort: 8080
  155. ```
  156. ```
  157. ### Configuration for Claude Desktop
  158. Add the following to your Claude Desktop configuration file:
  159. **Option 1: Using command name (requires `wikipedia-mcp` to be in PATH)**
  160. ```json
  161. {
  162. "mcpServers": {
  163. "wikipedia": {
  164. "command": "wikipedia-mcp"
  165. }
  166. }
  167. }
  168. ```
  169. **Option 2: Using full path (recommended if you get connection errors)**
  170. ```json
  171. {
  172. "mcpServers": {
  173. "wikipedia": {
  174. "command": "/full/path/to/wikipedia-mcp"
  175. }
  176. }
  177. }
  178. ```
  179. **Option 3: With country/language specification**
  180. ```json
  181. {
  182. "mcpServers": {
  183. "wikipedia-us": {
  184. "command": "wikipedia-mcp",
  185. "args": ["--country", "US"]
  186. },
  187. "wikipedia-taiwan": {
  188. "command": "wikipedia-mcp",
  189. "args": ["--country", "TW"]
  190. },
  191. "wikipedia-japan": {
  192. "command": "wikipedia-mcp",
  193. "args": ["--country", "Japan"]
  194. }
  195. }
  196. }
  197. ```
  198. To find the full path, run: `which wikipedia-mcp`
  199. **Configuration file locations:**
  200. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  201. - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  202. - Linux: `~/.config/Claude/claude_desktop_config.json`
  203. > **Note**: If you encounter connection errors, see the [Troubleshooting](#common-issues) section for solutions.
  204. ## Documentation Index
  205. - CLI usage and options: see [`docs/CLI.md`](docs/CLI.md)
  206. - API and MCP tools/resources: see [`docs/API.md`](docs/API.md)
  207. - Architecture overview: see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
  208. - User guide and troubleshooting: see [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md)
  209. - Development guide: see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)
  210. - Testing guide: see [`docs/TESTING.md`](docs/TESTING.md)
  211. ## Available MCP Tools
  212. The Wikipedia MCP server provides the following tools for LLMs to interact with Wikipedia:
  213. Each tool is also exposed with a `wikipedia_`-prefixed alias (for example, `wikipedia_get_article`) for improved cross-server discoverability.
  214. ### `search_wikipedia`
  215. Search Wikipedia for articles matching a query.
  216. **Parameters:**
  217. - `query` (string): The search term
  218. - `limit` (integer, optional): Maximum number of results to return (default: 10)
  219. **Returns:**
  220. - A list of search results with titles, snippets, and metadata
  221. ### `get_article`
  222. Get the full content of a Wikipedia article.
  223. **Parameters:**
  224. - `title` (string): The title of the Wikipedia article
  225. **Returns:**
  226. - Article content including text, summary, sections, links, and categories
  227. ### `get_summary`
  228. Get a concise summary of a Wikipedia article.
  229. **Parameters:**
  230. - `title` (string): The title of the Wikipedia article
  231. **Returns:**
  232. - A text summary of the article
  233. ### `get_sections`
  234. Get the sections of a Wikipedia article.
  235. **Parameters:**
  236. - `title` (string): The title of the Wikipedia article
  237. **Returns:**
  238. - A structured list of article sections with their content
  239. ### `get_links`
  240. Get the links contained within a Wikipedia article.
  241. **Parameters:**
  242. - `title` (string): The title of the Wikipedia article
  243. **Returns:**
  244. - A list of links to other Wikipedia articles
  245. ### `get_coordinates`
  246. Get the coordinates of a Wikipedia article.
  247. **Parameters:**
  248. - `title` (string): The title of the Wikipedia article
  249. **Returns:**
  250. - A dictionary containing coordinate information including:
  251. - `title`: The article title
  252. - `pageid`: The page ID
  253. - `coordinates`: List of coordinate objects with latitude, longitude, and metadata
  254. - `exists`: Whether the article exists
  255. - `error`: Any error message if retrieval failed
  256. ### `get_related_topics`
  257. Get topics related to a Wikipedia article based on links and categories.
  258. **Parameters:**
  259. - `title` (string): The title of the Wikipedia article
  260. - `limit` (integer, optional): Maximum number of related topics (default: 10)
  261. **Returns:**
  262. - A list of related topics with relevance information
  263. ### `summarize_article_for_query`
  264. Get a summary of a Wikipedia article tailored to a specific query.
  265. **Parameters:**
  266. - `title` (string): The title of the Wikipedia article
  267. - `query` (string): The query to focus the summary on
  268. - `max_length` (integer, optional): Maximum length of the summary (default: 250)
  269. **Returns:**
  270. - A dictionary containing the title, query, and the focused summary
  271. ### `summarize_article_section`
  272. Get a summary of a specific section of a Wikipedia article.
  273. **Parameters:**
  274. - `title` (string): The title of the Wikipedia article
  275. - `section_title` (string): The title of the section to summarize
  276. - `max_length` (integer, optional): Maximum length of the summary (default: 150)
  277. **Returns:**
  278. - A dictionary containing the title, section title, and the section summary
  279. ### `extract_key_facts`
  280. Extract key facts from a Wikipedia article, optionally focused on a specific topic within the article.
  281. **Parameters:**
  282. - `title` (string): The title of the Wikipedia article
  283. - `topic_within_article` (string, optional): A specific topic within the article to focus fact extraction
  284. - `count` (integer, optional): Number of key facts to extract (default: 5)
  285. **Returns:**
  286. - A dictionary containing the title, topic, and a list of extracted facts
  287. ## Country/Locale Support
  288. The Wikipedia MCP server supports intuitive country and region codes as an alternative to language codes. This makes it easier to access region-specific Wikipedia content without needing to know language codes.
  289. ### Supported Countries and Regions
  290. Use `--list-countries` to see all supported countries:
  291. ```bash
  292. wikipedia-mcp --list-countries
  293. ```
  294. This will display countries organized by language, for example:
  295. ```
  296. Supported Country/Locale Codes:
  297. ========================================
  298. en: US, USA, United States, UK, GB, Canada, Australia, ...
  299. zh-hans: CN, China
  300. zh-tw: TW, Taiwan
  301. ja: JP, Japan
  302. de: DE, Germany
  303. fr: FR, France
  304. es: ES, Spain, MX, Mexico, AR, Argentina, ...
  305. pt: PT, Portugal, BR, Brazil
  306. ru: RU, Russia
  307. ar: SA, Saudi Arabia, AE, UAE, EG, Egypt, ...
  308. ```
  309. ### Usage Examples
  310. ```bash
  311. # Major countries by code
  312. wikipedia-mcp --country US # United States (English)
  313. wikipedia-mcp --country CN # China (Simplified Chinese)
  314. wikipedia-mcp --country TW # Taiwan (Traditional Chinese)
  315. wikipedia-mcp --country JP # Japan (Japanese)
  316. wikipedia-mcp --country DE # Germany (German)
  317. wikipedia-mcp --country FR # France (French)
  318. wikipedia-mcp --country BR # Brazil (Portuguese)
  319. wikipedia-mcp --country RU # Russia (Russian)
  320. # Countries by full name (case insensitive)
  321. wikipedia-mcp --country "United States"
  322. wikipedia-mcp --country China
  323. wikipedia-mcp --country Taiwan
  324. wikipedia-mcp --country Japan
  325. wikipedia-mcp --country Germany
  326. wikipedia-mcp --country france # Case insensitive
  327. # Regional variants
  328. wikipedia-mcp --country HK # Hong Kong (Traditional Chinese)
  329. wikipedia-mcp --country SG # Singapore (Simplified Chinese)
  330. wikipedia-mcp --country "Saudi Arabia" # Arabic
  331. wikipedia-mcp --country Mexico # Spanish
  332. ```
  333. ### Country-to-Language Mapping
  334. The server automatically maps country codes to appropriate Wikipedia language editions:
  335. - **English-speaking**: US, UK, Canada, Australia, New Zealand, Ireland, South Africa → `en`
  336. - **Chinese regions**:
  337. - CN, China → `zh-hans` (Simplified Chinese)
  338. - TW, Taiwan → `zh-tw` (Traditional Chinese - Taiwan)
  339. - HK, Hong Kong → `zh-hk` (Traditional Chinese - Hong Kong)
  340. - SG, Singapore → `zh-sg` (Simplified Chinese - Singapore)
  341. - **Major languages**: JP→`ja`, DE→`de`, FR→`fr`, ES→`es`, IT→`it`, RU→`ru`, etc.
  342. - **Regional variants**: Supports 140+ countries and regions
  343. ### Error Handling
  344. If you specify an unsupported country, you'll get a helpful error message:
  345. ```bash
  346. $ wikipedia-mcp --country INVALID
  347. Error: Unsupported country/locale: 'INVALID'.
  348. Supported country codes include: US, USA, UK, GB, CA, AU, NZ, IE, ZA, CN.
  349. Use --language parameter for direct language codes instead.
  350. Use --list-countries to see supported country codes.
  351. ```
  352. ## Language Variants
  353. The Wikipedia MCP server supports language variants for languages that have multiple writing systems or regional variations. This feature is particularly useful for Chinese, Serbian, Kurdish, and other languages with multiple scripts or regional differences.
  354. ### Supported Language Variants
  355. #### Chinese Language Variants
  356. - `zh-hans` - Simplified Chinese
  357. - `zh-hant` - Traditional Chinese
  358. - `zh-tw` - Traditional Chinese (Taiwan)
  359. - `zh-hk` - Traditional Chinese (Hong Kong)
  360. - `zh-mo` - Traditional Chinese (Macau)
  361. - `zh-cn` - Simplified Chinese (China)
  362. - `zh-sg` - Simplified Chinese (Singapore)
  363. - `zh-my` - Simplified Chinese (Malaysia)
  364. #### Serbian Language Variants
  365. - `sr-latn` - Serbian Latin script
  366. - `sr-cyrl` - Serbian Cyrillic script
  367. #### Kurdish Language Variants
  368. - `ku-latn` - Kurdish Latin script
  369. - `ku-arab` - Kurdish Arabic script
  370. #### Norwegian Language Variants
  371. - `no` - Norwegian (automatically mapped to Bokmål)
  372. ### Usage Examples
  373. ```bash
  374. # Access Simplified Chinese Wikipedia
  375. wikipedia-mcp --language zh-hans
  376. # Access Traditional Chinese Wikipedia (Taiwan)
  377. wikipedia-mcp --language zh-tw
  378. # Access Serbian Wikipedia in Latin script
  379. wikipedia-mcp --language sr-latn
  380. # Access Serbian Wikipedia in Cyrillic script
  381. wikipedia-mcp --language sr-cyrl
  382. ```
  383. ### How Language Variants Work
  384. When you specify a language variant like `zh-hans`, the server:
  385. 1. Maps the variant to the base Wikipedia language (e.g., `zh` for Chinese variants)
  386. 2. Uses the base language for API connections to the Wikipedia servers
  387. 3. Includes the variant parameter in API requests to get content in the specific variant
  388. 4. Returns content formatted according to the specified variant's conventions
  389. This approach ensures optimal compatibility with Wikipedia's API while providing access to variant-specific content and formatting.
  390. ## Example Prompts
  391. Once the server is running and configured with Claude Desktop, you can use prompts like:
  392. ### General Wikipedia queries:
  393. - "Tell me about quantum computing using the Wikipedia information."
  394. - "Summarize the history of artificial intelligence based on Wikipedia."
  395. - "What does Wikipedia say about climate change?"
  396. - "Find Wikipedia articles related to machine learning."
  397. - "Get me the introduction section of the article on neural networks from Wikipedia."
  398. - "What are the coordinates of the Eiffel Tower?"
  399. - "Find the latitude and longitude of Mount Everest from Wikipedia."
  400. - "Get coordinate information for famous landmarks in Paris."
  401. ### Using country-specific Wikipedia:
  402. - "Search Wikipedia China for information about the Great Wall." (uses Chinese Wikipedia)
  403. - "Tell me about Tokyo from Japanese Wikipedia sources."
  404. - "What does German Wikipedia say about the Berlin Wall?"
  405. - "Find information about the Eiffel Tower from French Wikipedia."
  406. - "Get Taiwan Wikipedia's article about Taiwanese cuisine."
  407. ### Language variant examples:
  408. - "Search Traditional Chinese Wikipedia for information about Taiwan."
  409. - "Find Simplified Chinese articles about modern China."
  410. - "Get information from Serbian Latin Wikipedia about Belgrade."
  411. ## MCP Resources
  412. The server also provides MCP resources (similar to HTTP endpoints but for MCP):
  413. - `search/{query}`: Search Wikipedia for articles matching the query
  414. - `article/{title}`: Get the full content of a Wikipedia article
  415. - `summary/{title}`: Get a summary of a Wikipedia article
  416. - `sections/{title}`: Get the sections of a Wikipedia article
  417. - `links/{title}`: Get the links in a Wikipedia article
  418. - `coordinates/{title}`: Get the coordinates of a Wikipedia article
  419. - `summary/{title}/query/{query}/length/{max_length}`: Get a query-focused summary of an article
  420. - `summary/{title}/section/{section_title}/length/{max_length}`: Get a summary of a specific article section
  421. - `facts/{title}/topic/{topic_within_article}/count/{count}`: Extract key facts from an article
  422. ## Development
  423. ### Local Development Setup
  424. ```bash
  425. # Clone the repository
  426. git clone https://github.com/rudra-ravi/wikipedia-mcp.git
  427. cd wikipedia-mcp
  428. # Create a virtual environment
  429. python3 -m venv venv
  430. source venv/bin/activate
  431. # Install the package in development mode
  432. pip install -e .
  433. # Install development and test dependencies
  434. pip install -r requirements-dev.txt
  435. # Run the server
  436. wikipedia-mcp
  437. ```
  438. ### Project Structure
  439. - `wikipedia_mcp/`: Main package
  440. - `__main__.py`: Entry point for the package
  441. - `server.py`: MCP server implementation
  442. - `wikipedia_client.py`: Wikipedia API client
  443. - `api/`: API implementation
  444. - `core/`: Core functionality
  445. - `utils/`: Utility functions
  446. - `tests/`: Test suite
  447. - `test_basic.py`: Basic package tests
  448. - `test_cli.py`: Command-line interface tests
  449. - `test_server_tools.py`: Comprehensive server and tool tests
  450. ## Testing
  451. The project includes a comprehensive test suite to ensure reliability and functionality.
  452. ### Test Structure
  453. The test suite is organized in the `tests/` directory with the following test files:
  454. - **`test_basic.py`**: Basic package functionality tests
  455. - **`test_cli.py`**: Command-line interface and transport tests
  456. - **`test_server_tools.py`**: Comprehensive tests for all MCP tools and Wikipedia client functionality
  457. ### Running Tests
  458. #### Run All Tests
  459. ```bash
  460. # Install test dependencies
  461. pip install -r requirements-dev.txt
  462. # Run all tests
  463. python -m pytest tests/ -v
  464. # Run tests with coverage
  465. python -m pytest tests/ --cov=wikipedia_mcp --cov-report=html
  466. ```
  467. #### Run Specific Test Categories
  468. ```bash
  469. # Run only unit tests (excludes integration tests)
  470. python -m pytest tests/ -v -m "not integration"
  471. # Run only integration tests (requires internet connection)
  472. python -m pytest tests/ -v -m "integration"
  473. # Run specific test file
  474. python -m pytest tests/test_server_tools.py -v
  475. ```
  476. ### Test Categories
  477. #### Unit Tests
  478. - **WikipediaClient Tests**: Mock-based tests for all client methods
  479. - Search functionality
  480. - Article retrieval
  481. - Summary extraction
  482. - Section parsing
  483. - Link extraction
  484. - Related topics discovery
  485. - **Server Tests**: MCP server creation and tool registration
  486. - **CLI Tests**: Command-line interface functionality
  487. #### Integration Tests
  488. - **Real API Tests**: Tests that make actual calls to Wikipedia API
  489. - **End-to-End Tests**: Complete workflow testing
  490. ### Test Configuration
  491. The project uses `pytest.ini` for test configuration:
  492. ```ini
  493. [pytest]
  494. markers =
  495. integration: marks tests as integration tests (may require network access)
  496. slow: marks tests as slow running
  497. testpaths = tests
  498. addopts = -v --tb=short
  499. ```
  500. ### Continuous Integration
  501. All tests are designed to:
  502. - Run reliably in CI/CD environments
  503. - Handle network failures gracefully
  504. - Provide clear error messages
  505. - Cover edge cases and error conditions
  506. ### Adding New Tests
  507. When contributing new features:
  508. 1. Add unit tests for new functionality
  509. 2. Include both success and failure scenarios
  510. 3. Mock external dependencies (Wikipedia API)
  511. 4. Add integration tests for end-to-end validation
  512. 5. Follow existing test patterns and naming conventions
  513. ## Troubleshooting
  514. ### Common Issues
  515. #### Claude Desktop Connection Issues
  516. **Problem**: Claude Desktop shows errors like `spawn wikipedia-mcp ENOENT` or cannot find the command.
  517. **Cause**: This occurs when the `wikipedia-mcp` command is installed in a user-specific location (like `~/.local/bin/`) that's not in Claude Desktop's PATH.
  518. **Solutions**:
  519. 1. **Use full path to the command** (Recommended):
  520. ```json
  521. {
  522. "mcpServers": {
  523. "wikipedia": {
  524. "command": "/home/username/.local/bin/wikipedia-mcp"
  525. }
  526. }
  527. }
  528. ```
  529. To find your exact path, run: `which wikipedia-mcp`
  530. 2. **Install with pipx for global access**:
  531. ```bash
  532. pipx install wikipedia-mcp
  533. ```
  534. Then use the standard configuration:
  535. ```json
  536. {
  537. "mcpServers": {
  538. "wikipedia": {
  539. "command": "wikipedia-mcp"
  540. }
  541. }
  542. }
  543. ```
  544. 3. **Create a symlink to a global location**:
  545. ```bash
  546. sudo ln -s ~/.local/bin/wikipedia-mcp /usr/local/bin/wikipedia-mcp
  547. ```
  548. #### Other Issues
  549. - **Article Not Found**: Check the exact spelling of article titles
  550. - **Rate Limiting**: Wikipedia API has rate limits; consider adding delays between requests
  551. - **Large Articles**: Some Wikipedia articles are very large and may exceed token limits
  552. ## Troubleshooting Search Issues
  553. If you're experiencing empty search results, use the new diagnostic tools:
  554. ### 1. Test Connectivity
  555. Use the `test_wikipedia_connectivity` tool to check if you can reach Wikipedia's API:
  556. ```json
  557. {
  558. "tool": "test_wikipedia_connectivity"
  559. }
  560. ```
  561. This returns diagnostics including:
  562. - Connection status (`success` or `failed`)
  563. - Response time in milliseconds
  564. - Site/host information when successful
  565. - Error details when connectivity fails
  566. ### 2. Enhanced Search Error Information
  567. The `search_wikipedia` tool now returns detailed metadata:
  568. ```json
  569. {
  570. "tool": "search_wikipedia",
  571. "arguments": {
  572. "query": "Ada Lovelace",
  573. "limit": 10
  574. }
  575. }
  576. ```
  577. Example response:
  578. ```json
  579. {
  580. "query": "Ada Lovelace",
  581. "results": [...],
  582. "count": 5,
  583. "status": "success",
  584. "language": "en"
  585. }
  586. ```
  587. When no results are found, you receive:
  588. ```json
  589. {
  590. "query": "nonexistent",
  591. "results": [],
  592. "status": "no_results",
  593. "count": 0,
  594. "language": "en",
  595. "message": "No search results found. This could indicate connectivity issues, API errors, or simply no matching articles."
  596. }
  597. ```
  598. ### 3. Common Search Issues and Solutions
  599. - **Empty results**: Run the connectivity test, verify query spelling, try broader terms.
  600. - **Connection errors**: Check firewall or proxy settings, ensure `*.wikipedia.org` is reachable.
  601. - **API limits**: Requests with `limit > 500` are automatically capped; negative values reset to the default (10).
  602. ### 4. Debugging with Verbose Logging
  603. Launch the server with debug logging for deeper insight:
  604. ```bash
  605. wikipedia-mcp --log-level DEBUG
  606. ```
  607. This emits the request parameters, response status codes, and any warnings returned by the API.
  608. ## Understanding the Model Context Protocol (MCP)
  609. The Model Context Protocol (MCP) is not a traditional HTTP API but a specialized protocol for communication between LLMs and external tools. Key characteristics:
  610. - Uses stdio for local integrations and streamable HTTP for network integrations (`sse` retained for legacy compatibility)
  611. - Designed specifically for AI model interaction
  612. - Provides standardized formats for tools, resources, and prompts
  613. - Integrates directly with Claude and other MCP-compatible AI systems
  614. Claude Desktop acts as the MCP client, while this server provides the tools and resources that Claude can use to access Wikipedia information.
  615. ## Contributing
  616. Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  617. ## License
  618. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  619. ## Connect with the Author
  620. - 🌐 Portfolio: [ravikumar-dev.me](https://ravikumar-dev.me)
  621. - 📝 Blog: [Medium](https://medium.com/@Ravikumar-e)
  622. - 💼 LinkedIn: [in/ravi-kumar-e](https://linkedin.com/in/ravi-kumar-e)
  623. - 🐦 Twitter: [@Ravikumar_d3v](https://twitter.com/Ravikumar_d3v)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.